DEV Community

Discussion on: Design your code for readability

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.