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...
For further actions, you may consider blocking this person and/or reporting abuse
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:
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.
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.
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.
Thank you, Andy! Absolutely agree on machines. Happy you liked the post!
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 :)
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!
Very helpful article,Thanks.
Thank you, glad you liked it!
Really good article highlighting if the basics things are done right, it really helps in long run and helps you keep your code clean.
Thanks, Sumant!
Thanks for breaking down this very good reminder.
Thank you, Jess! Nice to see your comment.