51–60 of 100 posts
Earlier quoted context omitted.
>Comments are no exception. but they usually are.
Well this seems like a problem with code reviews (or lack of), rather than with the comments themselves.
I find that I have this problem with my own code. Ridiculous, but it happens.
How am I supposed to know if the comments have really helped the code, or if is that the code was just not written in a self-documenting way to begin with? Or, form the other perspective, how am I to know if the self-documenting code isn't as self-documenting as the original author likes to think? Perhaps even more importantly, how will I learn to take on that better style without examples to study?
In a world where we have a treasure-trove of great open source software, you would think the first step would be to point to exemplar examples to show exactly what can be gained by writing code in the prescribed manner. The "I do it this way and it is great. Believe me.", unfortunately, does not make for a good discussion.
This is an odd one for me, 90% of the time I wind up subconsciously ignoring comments that exist in code. It's almost as if I can't see them on the screen. I've been in at least one argument with a coworker where I realized I was ignoring the existence of the comment he was referencing a line above the code we were looking at. On the other side of that, I'm usually adding comments about what's going on all over the p…
If the comments aren't really that important it will start hurting my ability to read and understand the code quickly.
likewise, if you a comment I wrote, you better sit up and read because it's there for a very good reason.
I'm of the opinion that at the end of the day people need to be able to read code, not use comments as a crutch. There are times when non-obvious things should be documented so developer B doesn't go down the same rabbithole you did, but in general the code should speak for itself.
document gives the context, the code gives the details. If you have both, there should be no real issues with understanding what's going on.
Earlier quoted context omitted.
I hate this excuse. It seems like every lazy habit of programmers gets pushed onto the "business folks". Just because business folks don't know how to value certain developer practices doesn't let you off the hook. Just do what you have to do and if it takes longer because you had to learn how to do it, then it takes longer. Let the business folks tell you when it's taking too long to deliver features.
But it does. It depends on the organization, but there are groups where chugging coffee, talking a lot, and pumping out dozens of half-working features by coding like a drunk cowboy will get you promoted and recognized as a team player, while pushing back to take time and do things right will have you reprimanded. Many such cases out there.
A manager looks at a programmer bringing up something like unit testing as "why the fuck is he asking me about this, it's his job? Obviously because he's asking me it's outside of his professional ken, so that means it's going to take absolutely forever." Out loud he'll just say, "Can you just get the feature done?"
Don't ask, just do it. It takes as long as it takes. If they ask, just say it's not done yet.
Earlier quoted context omitted.
I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.
The thing is, if somebody forgets to update a unit test, it immediately becomes obvious. If somebody forgets to update a comment, it's very easy for no-one to notice until it's much too late. There's no way to automate that check. In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.
You could always use a tool like Danger (http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been.
From my experience there is a correlation between the amount of code comments and defects in the code. The more I see comments in the code base of a module, the more likely it doesn't have any (unit) tests and the more it has defects. Yet this may just indicate that the code is complex and therefore required comments and contains bugs. In any case, high comment density is a code smell.
LOL. Comments are not a part of the code. Good comments adds to readability, bad commenting style (e.g. enterprise style comments for everything) affects readability. Comments cannot add bugs to code. What you think about spaces?
I agree. I was talking about the _amount_ of comments.
Extreme example:
void foobar()
{
// iterate over the list
foreach(var item in list)
{
// send it
sender.send(item);
}
}
They also tell that the author didn't have a clear understanding why code comments should be written, so we may not trust his/her judgement in other programming decisions. The code is suspect. It's a code smell.
The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments. It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.
I feel like this translates to "lazy* developers are a problem" rather than "comments are a problems". Snarkily, how lazy* do you have to be to not even delete comments you make stale? * And not as in the virtues of programming lazy.
The closer a piece of documentation is to the code the more likely it is to be updated. External manuals always become stale and comments in C headers are more likely to be stale than comments next to the implementation in C source files (or in any language that doesn't even have that distinction). Comments directly next to complex formulae or other technical BS are most likely to be correct.
Some learn that then suggest getting rid of all comments or putting comments throughout all the code, but if we look at it another can can infer that some of it is code structure problems. A 2k line class with 200+ line methods with comments at the beginning of each method is more likely to have stale comments that any number of tiny classes with 10 line methods. Then comments on a 10 line method are more likely to be read too, because they need to describe less. Ideally they just add the "why" to the "what" the method's name provides. If the whole method and all the comments fit on the same screen then the dev ignoring it must be truly lazy.
Earlier quoted context omitted.
No, the reader must not need to read the function to understand how it works. The idea would be that the function names are so good that one does not need to read the function contents, right? But some things are complicated and may not be expressible with the function name alone. That's why people write comments. To help readers understand the code. Let's say I am implementing some algorithm. I may mention the perfo…
No. If I have a function and I need to understand _how_it works_, that is, how does it implement some algorithm, of course I have to read every single line of code to understand how it works! If the function is named "quicksort", for example, and I suspect it has a bug, I really have to read it to understand whether it implements the quicksort algorithm correctly.
The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments. It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.
If you update code without updating the comments and it gets past review you have bigger problems than them being misleading. Good comments are dependent on good developers.
> Code comments document the why, not the how. I disagree. The _what_ is what your comments should tell me. The contract, and its preconditions and postconditions. Nothing more, nothing less.
So where would you document the "why" then? This is often the question I find most difficult to answer when reviewing code (including my own) -- after all, I can ferret out the what from the code.
If we are speaking of API documentation (i.e. function or module documentation): The "why" can't be explained here. It's at the caller side.
There are more rare cases where it's reasonable to document the implementation of a function because there's a particularly tricky section of code -- and documenting the "why" makes more sense to me here.