3 ms·
I completely agree. For code that is unavoidably complex, I love this style too. I am all for code that is concise and whose syntax/naming is expressive, but s
by EB66 8y ago
I completely agree. For code that is unavoidably complex, I love this style too.
I am all for code that is concise and whose syntax/naming is expressive, but sometimes comments are necessary to clearly spell out the logic or business use case. Expressive code can only go so far. Well-crafted comments significantly reduce the amount of time required for other developers to dive in and become productive with an unfamiliar code base.
The key is keeping the comments up to date. There's nothing worse than an inaccurate comment. One's code review process must include a review of the comments accompanying the modified lines.
- chrisweekly 8y agoAgreed. Also, comments that emphasize the "why" over the "what" are not obviated by descriptive names.
- tetha 8y agoI've found it very helpful to rubber duck comments to get into the right why mode. Consider how you'd explain this piece of code to a less experienced guy on the team - and write down exactly that. Why was this added? Why was the old thing in place changed, what broke and had to be changed? Why didn't you do the other obvious thing? And remember - usually you should explain something until it's clear for you, and then one more step.
- ascar 8y agoOutdated comments that explain the business use case or purpose are still better than no comments. It gives you background information how the code evolved or what it was supposed to do. It's probably because reading comments only is worse than reading code without comments, that some devs developed an aversion towards outdated comments and thus comments in general. Comments are additional information and no source of truth, always take them as that and read code and comments.
- chris_wot 8y agoIt’s much worse in codebases that predate version control. At least a commit shows the context of why it was added.
- james_s_tayler 8y agoYeah and over the course of 2 or 3 decades of development a lot of software has moved through several different version control,ticketing systems and developers. So you wind up with files stating an author who no longer works there with an email address that the company used 3 acquisitions ago, a ticket number you aren't even sure what system it was for but you just know it isn't being used anymore and source control history that goes back 5 years out of a total 25 years of development. The entropy is real.
- chris_wot 8y agoYou just described LibreOffice!
- james_s_tayler 8y agoI just described a lot of offices.