Join devRant
Do all the things like
++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatar
Sign Up
Pipeless API
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple API
Learn More
-
Strive for self documenting code. Sometimes that's not possible, for different reasons. Could be time (you need to look for another job), technical reasons etc. Add comments to shed some light on why you did it that way.
The worst thing are comments that doesn't match the code, like refactoring left-overs. No comments are orders of magnitude better than wrong ones. -
@uxmedic agreed. But I argue that 90% of the comments in "well documented" code is superfluous. And as you say, often wrong which is even worse. Devs that can't read and understand code quickly should probably not be devs in the first place.
-
@undefined I agree that, but the skill of the dev and the focus on making code easy to read is key. Consider this example:
if (a > 3 && b < a)
{...}
vs.
if ((total > 3) && (average < total))
{...}
vs.
bool totalValid = ((total > 3) && (average < total));
if (totalValid)
{...}
Adding a properly named boolean makes it much more readable, and removes the need for comments all together.
Yeah, I've read Code Complete :)
Comments for comments sake or because of policy is just wrong. If it is self explaining, why bother? -
@uxmedic i agree, naming identifiers with proper names is good practice. Those extra parenthesis does not make it easier to read though. Why explicitly explain precedence? I would look twice and wonder why that was done, and probably conclude the programmer who wrote it does not know the rules of the language.
-
@undefined Extra parenthesises does in my opinion help clarify code. The example might not be the best one to highlight that. More important in maths to make precedence clear, for instance.
In general I'd say that extra paranthesis are cheap and rarely makes code harder to read. So my take is to be generous with them. 😊
"I wrote the code, I have to maintain the code, I wont need any comments"
*some months later*
Code comments be like....
Code comments #1: A way to document bad code that wasn't reduced to it's essentials and thus unreadable. Bad.
Code comments #2: A way to explain for non-programmers how the code works. Wrong place.
Code comments #3: Company policy. No one really knows why, but others do that, so we better do it to. The management sucks.
Code comments #4: Because some hip methodology/guru describes how to document code. After a few years, when the methodology has been (unofficially) forgotten, everyone still comments the code the same way. The old management sucked.
Code comments 5#: For insecure programmers who want to convince them self they understand the code they've written. Maybe apply at McDo?
Code comments #6: Some programmers are apparently paid by lines of code. Possibly understandable.
// Comments, anyone?
undefined
comments