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?
Ask HN: How to Write Readable Code
1–10 of 13 posts
Re: Ask HN: How to Write Readable Code
#2What 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”..)
Re: Ask HN: How to Write Readable Code
#3You 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.
Re: Ask HN: How to Write Readable Code
#4I’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”) ```
Re: Ask HN: How to Write Readable Code
#5What 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”..)
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);
}
function test_addition() {
int a = 2;
int b = 3;
int result = new Addition(a, b);
Assert.AreEqual(result.Sum(), 5);
}
Re: Ask HN: How to Write Readable Code
#6You 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.
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.
Re: Ask HN: How to Write Readable Code
#7I 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.
Re: Ask HN: How to Write Readable Code
#8[deleted]
Re: Ask HN: How to Write Readable Code
#9What 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”..)
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…
I was having trouble visualizing what OP meant, and this is a great explanation!
Re: Ask HN: How to Write Readable Code
#10I’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”) ```
And this is all you need to do really.