Ask HN: How to Write Readable Code

[marijnz0r]

Hi HN, I write code and unit tests for other departments in my company. For me, writing code in a programming language feels natural, so I like to use the notation of the language itself. A colleague likes to write code more like prose so someone from another (non-IT) department should be able to read it. How do you deal with this in your company? I think I read an article about this a few days ago, but I can't seem to find it anymore. Does someone still remember this?

[me_me_mu_mu]

I’ve worked with “code like prose” people and found them pretty difficult to work with. I’ve also found most of them to be not that great technically or they have exclusively Ruby on Rails backgrounds and can’t seem to function on any other technology or approach.

I don’t think the sales guy needs to be able to read channel handling logic or care about how the react code is organized.

Engineers should write good code that can be easily understood and modified by other engineers. Are engineers going to cold call people or run the financials? No their job is to build systems and keep them running.

[notadev]

I’ve always tried to use naming of variables and methods to make it obvious what the code is doing. Something like:

``` if service_is_disabled: start_service() else: send_notification(“Service is running”) ```

[peakaboo]

And this is all you need to do really.

[eslav]

What does “code like prose” look like? I had a group project in college with a guy who used MS Word to write code in paragraphs..formatted like an English paper (I’m not kidding); is this what you mean?

(Looking back I often wonder how long this guy wrote code like this before someone said “knock it off”..)

[marijnz0r]

Regarding a unit test it looks something like this in pseudocode:

  function test_addition() {
      given_two_integers(2,3);
  
      when_summed_up();
  
      then_the_result_should_be(5);
  }

Whereas I would prefer something like

  function test_addition() {
      int a = 2;
      int b = 3;
  
      int result = new Addition(a, b);
  
      Assert.AreEqual(result.Sum(), 5);
  }

For a non-coder it might seem more intuitive to read the first example, because it only contains natural language. For a coder it seems more intuitive to read the second example, because it prevents "method hopping" (I have to go into the methods from example one to see what's actually happening inside them).

[mvaliente2001]

I think it's important to keep a consistent style in a repository. Ideally, the style should be kept _among_ repositories too, but given that different people like different thing, allowing them to explore the pros and cons might be a better strategy to achieve it.

[100011_100001]

You might want to look at BDD. It's a way to be able to discuss what has to happen and use code to make it happen.

[marijnz0r]

Thanks for the recommendation. I've read the book by Eric Evans and I like the first chapters about creating an ubiquitous language. I'm trying to figure out how to create a balance between the spoken language in code and the actual implementation of the code.

[gushogg-blake]

Literate programming maybe?