DEV Community

Design your code for readability

Elena on June 30, 2017

This article was originally published in my blog smartpuffin.com. So, how do you usually code? You have a task: add this thing to that place. Fir...
Collapse
 
hawarioware profile image
Wajdi Al-Hawari

Great article! I love some of your examples. "...files as big as 40000 lines. Forty thousand".

On your mention of "clever tricks and obscure features", this actually took me back to when I was first learning Python and discovered lambda's and comprehensions. I promptly proceeded to shove as much as I could in a single comprehension, with "fancy" lambdas. It was a nightmare! I really hope whoever saw that code after me quickly got rid of it. And if this person happens to read this...I'm really sorry. :)

On the topic of comments, your examples actually bring up a case where comments are definitely needed, however, what I find interesting, is that, at least for myself I've found when I have to justify using comments it meant my code was not clear enough, so I would review my code and ask:

  1. why am I making this comment?
  2. is there any way I can break the code down further so it does not need a comment?
  3. Instead of a comment, how can my doc string be better (or even introduce one!) to help clarify the functionality of my methods?

However, more so, I would actually depend more on my tests to be the documentation for the code. I'd be interested to know what you think about that? I've found it's helped me structure coherent tests that were well named that helped explain how everything works in the code.

This inadvertently got me to make smaller commits for features that were more relevant to the exact task I was tackling for the given story.

Collapse
 
ice_lenor profile image
Elena

Thank you Wajdi, nice to know you like the article!

Love your lambdas example :). I wonder if you tried to read your code some time later? What did you think of it?

40 000 lines is not a joke, unfortunately. :(

Regarding the tests: in my opinion they help a lot to understand the contract. But not the implementation. So sometimes they're not enough. For example, if I'm doing something for legal reasons, or if it's complex business logic, or it's a workaround, I always write a comment explaining that.
With only a test you can see the result, but don't know why it should be like this.

A docstring is sort of a comment as well, isn't it? Of course, it's also very helpful.

Ultimately, I try to look at the code as if I see it for the first time, and explain it to myself with comments.

Collapse
 
andylincoln profile image
Andy Lincoln

Really enjoyed this post!
Wholeheartedly agree about your stance on comments, they are just as important as the code.

It also made me think of a quote from a programming book I read in college, Structure and Interpretation of Computer Programs by Harold Abelson

“Programs must be written for people to read, and only incidentally for machines to execute.”

If I'm ever a team lead I'm going to drive that point home in every code review and have my team members read this post.

Collapse
 
ice_lenor profile image
Elena

Thank you, Andy! Absolutely agree on machines. Happy you liked the post!

Collapse
 
damcosset profile image
Damien Cosset • Edited

Good article. Always something we have to be concerned about. I took it upon myself to configure a linter for new projects at work. At least, the repository will have the same syntax everywhere. Rules can be changed or added later. Not perfect, but it feels like only one person wrote the whole thing.

Now, on to all the other reminders :)

Collapse
 
ice_lenor profile image
Elena

Thanks, Damien! For my previous project we had a linter too - helped a lot. Also the team climate has improved. No one was arguing about whether to put spaces after brackets when calling a method or not. The productivity has increased)). Only positive consequences. So yes, great advice!

Collapse
 
noufal_06 profile image
Noufal A

Very helpful article,Thanks.

Collapse
 
ice_lenor profile image
Elena

Thank you, glad you liked it!

Collapse
 
asynccrazy profile image
Sumant H Natkar

Really good article highlighting if the basics things are done right, it really helps in long run and helps you keep your code clean.

Collapse
 
ice_lenor profile image
Elena

Thanks, Sumant!

Collapse
 
jess profile image
Jess Lee

Thanks for breaking down this very good reminder.

Collapse
 
ice_lenor profile image
Elena

Thank you, Jess! Nice to see your comment.