4 ms·
I have regretted when you fail to follow that lesson. I did a survey once in about 3/4 of the comments were either wrong or useless. Examples: //Add 1 to x x
by readthenotes1 2y ago
I have regretted when you fail to follow that lesson.
I did a survey once in about 3/4 of the comments were either wrong or useless. Examples:
//Add 1 to x
x+=1;
//Add 1 to x
x+=2;
//Seconds per normal day
x = 86400;
--
"Why not" comments are incredibly valuable except they suffer from explanatory decay as much as other comments.
The hope behind Intention Revealing Names is that the dissonance will be too great for the subsequent developers to ignore when they change the code.
Of course, that isn't always true.
- g-b-r 2y agoAn outdated comment is at least a very strong signal that the code might be wrong And, you definitely had little experience with under-documented code
- GianFabien 2y agoFor me the quality of comments, somewhat based on the metrics that @renhanxue mentions, is a code smell. If code is poorly commented (by my standards) then I treat the actual code with suspicion.
- dspillett 2y ago> An outdated comment is at least a very strong signal Also: if the code and the comments appear to disagree, there is a reasonable likelihood that both are wrong in some way.
- gus_massa 2y agox = 86400 If I were forced not to write comments, I'd write that as x = 24 * 60 * 60 and let the compiler optimize that.
- hansvm 2y agoWhen writing it inline, I like this approach. I like even better when these things have names. Something like `std.time.s_per_day` or `time_utils.s_per_day`. Then in the one place they're defined, use a pattern like the above to make them easy to reason about.
- DanHulton 2y agoOne step further: DAY_IN_SECONDS = 24 * 60 * 60
- throwaway14356 2y agoSECONDS_PER_MINUTE = 60; MINUTES_PER_HOUR = 60; HOURS_PER_DAY = 24; DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY
- CRConrad 2y ago> DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY Naah. DAYS_PER_SECOND = 1 / (SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY) ;
- jjav 2y ago> I did a survey once in about 3/4 of the comments were either wrong or useless. > Examples: > //Add 1 to x > x+=1; If 3/4ths of comments are like this, maybe show a sampling of public source code (e.g. from github) that shows how prevalent comments like this are in any real codebase. I've been programming since 1982 and have never seen this type of "add 1 to x" comment in real code, outside chapter 1 of some intro to programming book.
- dllthomas 2y agoI once came to a complicated, multi threaded C++ program and saw: using namespace std; // using namespace standard
- f1shy 2y agoI'm working RIGHT NOW in a codebase where before each function definition there is a comment "// Function"
- bccdee 2y agoI wonder if that's intended for a specific workflow, e.g. ctrl-f "Function" enter-enter-enter-enter to cycle through all the functions in the file. That's the only reason I can think of for writing those comments.
- f1shy 2y agoWith a half decent IDE you do not need it. It is inexcusable.
- bccdee 2y agoOh I agree, but the person who put them there must have had some sort of reason, even if it's a bad one.
- dllthomas 2y ago> With a half decent IDE you do not need it. I agree. > It is inexcusable. I think it can be quite easily excused on grounds of triviality, though whether that's appropriate may depend on context.