Best practices for writing code comments
stackoverflow.blog
stackoverflow.blog
And that whole thing was evangelized by Uncle Bob and the Agile wrecking crew. Before long it was bad to use comments, switch statements, or new up an object. This, in turn, led to the TDD movement, Agile only movement, enterprise patterns for all projects movement, and I'm sure there are others I'm forgetting.
Please comment your code. Tell me what you're trying to accomplish with this block of code. The function name doesn't always suffice. And I don't want to stare at it for 15 minutes, or re-format your 160 column LINQ statement, or Google your regex so I can read what it does on StackOverflow.
Even commenting pseudo code would be fine.
* If you ever had to maintain a code base you didn't design (who haven't ???) how can you not want to have as much paper trail as possible? Especially when the original authors move on.
* I don't remember discussing documentation (or even testing) styles/preferences during interviews. I don't remember managers making it a priority or educating the unwilling, even in large companies. So it's clearly not important from the business perspective. The closest I can remember was a mad rush to create runbooks after a particular nasty prod incident.
We live in a world of microservices. So you routinely work with multiple repositories. In larger companies developers routinely move to different teams in a couple of years. There's always another AWS service or non-relational data storage. It's interesting to notice that in other domains dealing with this kind of complexity and constant change it's expected to have written notes all the time. Think of medical doctors or aircraft maintenance crews.
When I was younger I kind of trusted that "self documenting code" promotion. As much as the Refactoring book was right this idea proved to be just wrong. Think about "business logic". Including the classical "converting XML/JSON to other protobuf/JSON". There's no grand theory here, just multiple confusing details influenced by previous versions, legacy ontologies, dependencies on other teams. Naming conventions won't help much, not to mention "the two most difficult problems in CS".
I think there's some correlation between poor documentation and missing tests. And the lame excuse is always the same - not having enough time. Even for obvious error-prone things such as calendar calculations or parsing deeply nested data received from the outside world. Or how to build and run a service.
Another correlation is between clear/structured thinking and how easy it is to explain the results. A reasonable functional decomposition and popular idioms/patterns/libraries documented elsewhere enable terse descriptions.
I see documentation as fungible. There are multiple somewhat interchangeable places information can be stored in. JIRA descriptions, commit messages, "javadocs", MD files (previously known as GOOG docs, wikis, Word documents). From what I've seen the people who have enough discipline to use one usually have others in place too.
Software development is very much a learning process. So other people will have to repeat it unless you summarize your findings for them. For some low-level details you could be one of them after not working on a particular component for long enough.
I learned this rule viscerally early in my career. Back in the golden age of Experimental Flash Art there was an enigmatic site called "flight404", and one day the site's author released source files for some of his more popular projects. All the Flash devs in my office started poring through them, and soon after my boss called me over to show me my own name in one of the comments!
Apparently the author (Robert Hodgin - whom I very much looked up to) had asked for help anonymously in a forum, and I had helped him out so he credited me in a comment (just for his own reference - in those days there was no Flash open source community and designers rarely distributed their source). That experience made me pretty obsessive about crediting outside influences in my source code whenever I get the chance.
Exceptions are e.g. if it's something exceptionally tricky or a hack of some kind that is kind of important. It doesn't happen all that much because the stuff I work on is simple. If I was going to do a lot of "commenting" I would prefer to write and update good documentation that gives an overview of how different things work together. The nitty gritty changes too often and is not that important in the grand scheme of things.
Don’t they disappear when someone squash merges branch where a file is both renamed and changed (a lot)? Or, at least, when somebody decides to move to code to another repo, and doesn’t bother bringing the git history along.
Why doesn't the author make commits that are not useless?
Why squash everything into a single commit? Why not 2 commits, 3, 5?
Comments in Git commits are bad. Just comment the code and make sure the comments are updated while you're in the code. You can also look at them in a code review. The argument that they get outdated is easily remedied, but people just want to keep claiming they write 'self documented code.'
People will invariably forget to update comments and unless the comments show up in context lines of the diff associated with a change, it's likely that reviewers will overlook the need to change them.
To me both are important but for different reasons. I don't want to search the blame history of a line of code if a simple comment had been enough, neither would I want to primarily use code comments when bisecting.
It depends on who the “someone” is I suppose.
I typically squash my own commits, and as part of that I aggregate all of the commit messages into a single message with all of the relevant details (and leave out the “fixed typo” type stuff that’s not relevant.)
From the complaints that people are raising here there must be dev shops where someone else decides to squash a bunch of commits and throw away the messages.
Whats even more difficult is searching through a code base when the documentation isn’t in or near the code. I don’t know any IDE or editor that makes it easy to search though git commit message and source code at the same time.
On top of that, do you review git commit message in code review? Do you aks people to improve descriptions, typos and language in commit messages?
git log --follow -p file
git log -p -L:show_commit:builtin/rev-list.cAny editor from Jetbrains with the GitToolbox plugin does that.
What I truly care about is why something is the way it is, what is the rationale behind it, how it works with other parts of the codebase, what problems it solves, what is tricky about it, what to pay attention to and so on. I don't care at all about the code that was written and an explanation to it because this I can read myself in the code. The best place I've found for this is a code commit because it can tie different parts of the codebase together and add a lot of context to a change. I commit heavily and don't squash. A long comment in a commit that contains all file changes related to a certain feature, bug or whatever adds a lot more information than a comment in one file. When other people do it, it helps me a lot more than chasing their (outdated) code comments throughout the codebase.
But if that doesn't work for you, then don't do it. Just don't be dogmatic and dismissive. I accept there might be situations and codebases where this doesn't work.
I think JetBrains is probably the best of the IDEs
But for regular "explanatory note about this variable/function/etc" comments, how does one work if those things are in commit logs? If you're reading code and something is unclear, do you look back through the commit messages of every commit that's ever touched that line, just in case one of them has something relevant?
But for the most part I feel like comments should be automated tests. If a line is there for an edge case it should have a matching test for that edge case.
The only exceptions I see are for performance optimizations or some other situation where you can't easily test.
Feature A
"It should return X in [some edge case]"
That's where any link to a use case should be.
How you check the commit history is beside the point - the question is, do you read the entire commit log history for a chunk of code before editing it?
If not, any comments there might as well not exist - functionally speaking you're maintaining an uncommented codebase.
> That’s horrible because the git commit messages are easily lost, disconnected or hard to find in any reasonably active codebase. For example as soon as you do a change and move a file it almost always disconnects from the previous change history.
Learn your tools or get better ones, `git log --follow` has no issues with renames, and when files get munged in ways it can't handle (e.g. content is split out or merged) it's easy enough to stitch back, and good annotate UIs (Jetbrain's is stellar and one of the few things I don't use magit for) make flitting through a snippet's history trivial.
Meanwhile finding removed comments is nearly impossible (VCS are nowhere near as good for finding when was removed than when it was added), and comments can easily drift apart from their point of origin as developers aren't too careful about maintaining them when adding unrelated comments.
> On top of that, do you review git commit message in code review? Do you aks people to improve descriptions, typos and language in commit messages?
Bet your ass I do.
Absolutely I do. The commit message is part of the commit just like the code; why would it be excluded from review? The number of times that a good commit message has helped me when dealing with a bug, and that a poor one has stymied me, have firmly convinced me that they are just as important as any other project documentation. They should be clear and informative, and I ask for those aspects to be improved when needed.
Only until someone moves a file to a new directory. Now this file shows up as a new file with no history.
Also, you hope to never change your version control system because that change will erase the history.
Relying on commit messages is sometimes just not good enough.
Git will usually be able to link the two back, unless the move was combined with a lot of changes, as it does not record moves but infers them.
Even if it can't link them, the "creation" commit will visibly remove the old file, at which point you can... log / blame on the previous location and keep going.
> Also, you hope to never change your version control system because that change will erase the history.
Of course not, there are conversion tools between basically all VCS, and anyone tasked with such a migration who is not a complete goober will use them in order to maintain the historical record.
At $dayjob we've got history spanning over 3 different VCS and more than 15 years, and that's including weird stuff like splitting and merging repositories.
You can also format your hard-drive, yes.
I try to write good comments and commit messages. Comments are typically along the lines of explaining what was done and how for a particular block of code or method. Header comments include a list of parameters, return values, side effects, class variables, etc. Commit messages explain what was done or changed and why.
These are only useful for public stuff and in special circumstances in other cases. Sadly a lot of companies make stylecheck require them on every little private method which makes each file 50% longer for no reason and drown the really useful comments in noise.
> Comments are typically along the lines of explaining what was done and how for a particular block of code or method.
The problem with that is that the block of code that you explain will often call other code, and then that other code will change for other reasons (preserving the correctness but not the initial design that was in the comment) and then that explanation higher in the callstack won't be true anymore. It's nice to pretend we always check everything that calls our code all the way up when we change stuff, but in reality if tests pass and the code works - we often don't check for comments up the callstack. So the comments will drift away from the truth with time.
Comments in commit messages are much more likely to be true than static comments in code (for example if you refactored some method signature as part of the change - every call site will have the updated commit message automatically). If you comment in the code manually - you will probably not notice that you have to change a comment block 5 lines above the changed function call - it won't even show in the diff - so the comment block won't be true anymore).
The point of a good comment is to guide later development - to say "here's something you should know before editing this code". If you put information like that in commit logs, then that implies that anybody who updates any part of that codebase must first read every log for every commit near what they're editing. If they don't (and they presumably won't), they'll never see that "here's why we're not doing X" comment before they change the code to do X.
Meanwhile, it's true that comments can drift away from truth over time, but putting them in commit logs doesn't change that in any way. An inline comment that's stale can be updated (and doing so is part of the job!). But a commit log comment that's no longer accurate will stay there forever, waiting to mislead anyone who finds it. The promise that it was accurate when originally written is of no practical use later on.
Changing revision control system or copying code from one package to another can lose them.
The only durable documentation I've seen is in the source code
They get orphaned by slightly wonky merges. The underlying code gets updated or refactored, but the comments remain. When they are correct, they’re useless 90% of the time (at least in codebases whose linter requires doc comments). Even the accurate comments tend to drift with age and become inaccurate unless they’re carefully maintained (which they almost never are).
It’s really hard for me to figure out the balance.
For exceptionally good codebases (Redis, SQLite come to mind), the comments are a godsend.
For mediocre codebases, the comments are largely a waste of time at best, misleading and time-wasting at worst. And most of us, I suspect, are working on mediocre codebases.
At least classes and public methods should have comments (except trivial ones).
[1] https://docs.rs/chrono/0.4.19/chrono/naive/struct.NaiveDateT...
Something like this with a discrete task that can be checked on code review would help immensely, I think.
Adding a mechanism to publish the docs (maybe part of CI/CD?) would make maintenance way easier, it's something I would love to test out.
Not much time to work on it lately. But, I’ll Show HN when I put it on Github.
> Rustdoc actually uses the rustc internals directly. It lives in-tree with the compiler and standard library. This chapter is about how it works. For information about Rustdoc's features and how to use them, see the Rustdoc book. For more details about how rustdoc works, see the "Rustdoc internals" chapter.
docs.rs runs it for every crate (rust library) uploaded to crates.io.
When actually working with rust, I recommend running `cargo doc --open` semi frequently. It generates that documentation from all your dependencies, and your own code, links it all together (with search no less) and opens it in a browser.
Note that it only uses doc comments, which are distinct from normal comments (/// instead of //, only allowed in certain places, //! Instead of /// to apply to the parent item instead of the next item).
Bad codebases are ones that basically are throwaway or depreciating assets. As you say, we practically all work on these except the lucky few.
Code does what it's written for. But it does not explain intent. Write that on a comment, link to the relevant ticket and document
It's also a misguided tools upgrade if they have no way to redirect, convert or otherwise handle old links.
If you link to Sharepoint or something it's useless as soon as that link changes.
But make the boss understand...
Normally the comment is an explanation of the intent but the referenced ticket has the full discussion and backing data that led to the decision
I very often nudge people to remove their comments entirely. Less experienced devs often write comments to explain code, instead of spending time on making the code itself readable/understandable. I often ask: “Can you modify the code such that the comment will become obsolete?”
Comments there will be tied to that version of the code, can never go out of sync.
It's also good to learn how that piece of code evolved and what reasons to change. Avoids repeating past mistakes.
Yes, code should be easy to understand.
But well-written comments that explain assumptions and intent helps as code evolves over time.
Also, comments are quicker to scan than code itself.
A good comment can indicate code that can be ignored for the purposes of certain troubleshooting.
Finally, junior developers usually write code that is difficult to understand and don't comment.
I've rarely ever seen a junior developer that both writes unreadable code and takes the time to write comments.
Usually comments are a sign of seniority, someone who has pity on those who will come after him/her.
And thus that person tends to also write understandable code.
Perhaps there's an uncanny valley in between where comments are a band-aid for complexity, but I have never observed that in years of working with many developers.
Bigger architecture decisions should go in ADRs (again, explain the why) but smaller stuff like explaining why you monkeypatched a library can save future devs a lot of lost investigation time and pain. Maybe by the time they are reading your comment/code, the patch you wrote is supported in the main library!
Before Ddoc, the D standard library was inadequate, totally wrong, or missing entirely. After Ddoc, it became reasonable (though no documentation is perfect). Further improvements were an ability to actually run the example code in the Ddoc comment as a unit test.
The end result is the entire documentation of the D runtime library is generated by Ddoc from the source code.
Though embedding unit tests in API documentation is less common; the only other languages I'm aware of that support it out of the box are Python and Rust. A Google search turns up some implementations for other languages, like C++ and Haskell, but I don't know how widely used they are.
Regardless, I definitely agree that it's a very important and useful feature.
The problem with DOxygen was, it wasn't installed automatically! It was extra work to go get it and install it, so it never happened. What a builtin Ddoc does is:
1. It's always installed
2. It's always matched to the current compiler (one never has a mismatched set)
3. It is standardized (code using DocX is not mismatched with other code using DocY)
4. It can take advantage of the compiler's available semantic information
5. Don't have to beg documentation tool vendor to add features we need. For example, Markdown support was recently added. Didn't have to ask or beg. A Ddoc user simply added it
These advantages are enormous and transformative. Minimizing friction matters a great deal.
C and C++ do not have builtin documentation generators. I ask you, of professional C/C++ code you've seen, how many consistently and properly documented the function interfaces? In my experience, it's rare. It's much more common in D, and that's entirely due to Ddoc.
// Adding this because XYZ said so
1. There's a chunk of code that, on first reading, could be clearer/simpler/more idiomatic.
2. There's a good reason not to use the obvious approach, and do something else instead (maybe performance).
Then comment to explain why the obvious path wasn't taken. No matter how well written, code alone can never explain "why not". I've found this invaluable, even looking back at my own code.
Possibly unless your entire codebase is literate, and code is secondary to comments.
During the development you are mostly likely looking at commits, or PRs, so that makes sense.
But if its long living piece of code, people will get you your code via following function/method chains or just browsing the source not commits. While you can use git blame, and then figure out the commit, and then read last few commit messages, putting comment on code is easier on everybody.
At the very least, comment these situations.
inc al ; add one to al register
Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.
If effort is linear then, by definition, you should never put more than 50% brainpower in to your code.
I'm not sure I want to increase the effort I put in though.
However most "clever code" we come across is lopsided in this tradeoff, and might even require cleverness to understand, which it turns out is not very clever at all.
> Fools ignore complexity. Pragmatists suffer it. Some can avoid it. Geniuses remove it.
My only rules to write comments are:
- Add “why” comments when you write the code
- Add all the other comments when you read the code, and don't understand
StackOverflow looking to get more backlinks from GitHub/GitLab :)
I have no particular attachment to SO, especially after the way they handled their public drama recently.
That said I put a link to SO any time I have to look something up there and it’s not immediately obvious from the naming/docs why it does what it does. I also try to sum it up in a sentence or two if I can and if it doesn’t distract from understanding the larger goal of that section of code.
Links are mutable, links die, SO answers can be edited. Include any information needed to understand the code into the comment and proper copyright acknowledgements if you copied it (assuming the license allows it).
Then you can link the standard, or at least the Wikipedia page, and I would lean towards this if I don't expect readers to know a bit about the domain. But if you don't, someone can still find an authoritative source with a single search.
Write TODO and NOTE and use a tool to find all your special comments that show unfinished features and investigations. Scan through regularly to make sure the comments still make sense.
Comments not containing special strings should just be "why" explanations, eg "we sort the bids in the reverse order to the asks because the best bid that the highest price". So generally something where the code has special cases that are explained by the domain.
You shouldn't comment on things that are obvious within your domain.
Now you may put a comment if instead you sort things in the reverse order than usual, for example so that you can implement adding/removing a price level at the top more efficiently with std::vector (which is only efficient fot additions/removals at the back).
Though in that case you should probably have a comment explaining why you didn't use an std::deque.
The advantages of vector over deque should be well known to any C++ programmer.
1/ API documentation, which is a must unless you can cover everything with examples, which are better.
2/ Internal comments explaining how things fit together. I don’t do any of this any more. If my code doesn’t make this obvious, my code is wrong and gets refactored and functions get better names.
3/ Warning signs. Invaluable! “You might think that this is wrong and change this to use / instead of //. Nope! Don’t make that mistake!” kind of thing. Few and far between, hopefully.
I agree examples are great for a variety of purposes, but they're no substitute for detailing the API endpoints, authorization mechanism, data types, etc.
I wish that could be done for C and C++. Too bad it can't, because of copyright issues. I don't link to online descriptions of the C std library, because I've found errors in those online rewrites (rewrites because of, again, copyright issues).
So, for C and C++, I just cite the paragraph number in the standard.
Comments are in my native language, if i am absolute sure, that this code will not be used by any other people.
Same language as the codebase, so usually english.
It can make sense for the codebase to use local naming conventions e.g. for legal, accounting, or administrative concerns: the ideas and concepts don't necessarily translate easily (or at all) and all the reference documents are in the local language in which case the codebase will probably be better off using the local language, and both comments and commit messages should match.
> People copy a lot of code from Stack Overflow questions and answers. That code falls under Creative Commons licenses requiring attribution. A reference comment satisfies that requirement.
This is incorrect (or, more accurately, not enough). The license is CC-BY-SA: the BY part requires attribution, but the SA part also requires that you share your own code.
In regard to rule 5, I've found it's a bit more nuanced than:
> Without the comment, someone might “simplify” the code or view it as a mysterious but essential incantation. Save future readers time and anxiety by writing down why the code is needed.
What is idiomatic? Well that depends on nested organizational requirements merged with some community merged with developer experience.
I have some methods:
public void doSomething() {
myType foo = createType();
foo.monitor();
}
public myType createType() {
return new myType();
}
>I'm not sure why this has rule 8.
It's oriented toward maintainers. Hence little attention to larger architectural questions or business strategy.
What we should do is document the code, short and consise description of classes, methods and functions. This will then act as a reference, when names inevitably fall short.
From this discipline, comments above code-blocks should explain what's missing in code to a future reader - probably yourself even. But a basic explanation of "What the heck is this? What is it for?" might be in order, if not already given.
How to implement this depends on needs and tooling.
The bigger picture belong in design documents, with references to components.
It can impact the memory of runtime-oriented languages, especially if they keep the text around (e.g. for reflection or whatever) but that's about it.
Writing and then maintaining comments is an expense. Your compiler doesn’t check your comments so there is no way to determine that comments are correct. You are, on the other hand, guaranteed that the computer is doing exactly what your code is telling it to.
Unless your team has the discipline to maintain them, don't litter the code with comments. Put it in the commit message. Obsolete and incorrect comments are just confusing.
What I sometimes do is write comments before I implement something. This provides a clear idea of what I need to do and where. Then when it's done I cut it into commit message or note
I regularly recommend it to colleagues who make the bold claim that "No one needs comments. Good source code can and should document itself". The article covers pretty much all the types of comments and rules discussed in the OP and others not mentioned there.
It's weasel words, intended to give more credence to the advice that it has proven.
As for these recommendations, these aren't bad or good, even worse, these are mediocre.
Want my advice? Have your logging statements double as comments. Logging and comments both should concentrate around difficult code. So why double them up?
Javadoc was the last "good" idea in comments I ever saw: generate documentation from comments. Unfortunately it didn't provide enough autogeneration abilities or semantics to track evolving code. Nor do comments and javadocs integrate git history or help indicate heavily modified and evolved code, something I think could also be done.
I believe Rust enables some use of markdown in comments as well, that is a good idea.
IDEs, even intellij-level, don't really help out with comments and doc-comments much either.
For myself, and my approach, I'm always a bit leery of "hard and fast" rules. I prefer a heuristic approach to almost everything that I do. Also, I've found that code comments are only part of the mix. As the article indicates, the code, itself, should be written in a clear fashion, and supporting materials (which can include seminars, tutorials, examples, unit tests, and test harnesses) are an important ingredient.
I wrote my own approach to documentation in this post: https://littlegreenviper.com/miscellany/leaving-a-legacy/
It's a long read. I don't think many people really give it much of a gander.
// Receives n >= 0 and returns the n'th fibonacci number
int fib(int n) {
// We use the memoized version of the algorithm.
}To me, the most important is that comment isn't the code. Then what it's and why we write it. Now, common becomes normal writing.
So the rule is? Know your audience.
Just think who you write this comment for and explain that to them. It helps a lot to guide people through what the code do. Especially in even driven code.
Imagine this pseudo code:
send_event({name: 'a', {props: name: 'a"}})
Why do name show up twice there? Without comment noone know why except people have business visbility. Because apparently some down the life consumer need the name in `props` and it cannot access the root of the object.
So. my best practice is know your audience when writing code comment.
Why does my text editor think that, e.g., a function call should be blue and keyword arguments to it should be bright orange, but a comment should blend in to the background? Have them be bright green or something! If something merits a comment, it should be the most visually important thing in that block. At least that'll make bad (pointless, redundant, or outdated) comments stand out enough to annoy people.
If anyone knows how to make Sublime Text do this I'll give them a big virtual hug. :)
So the documentation is the easy way for humans to understand what is going on and when I want to know the details, I can jump into the code. And just if the code itself is so complicated or its implications are not easy to understand (which should rarely be the case), then comments should be used.
However, the problem with this mantra is, that the original authors often don't know/want to know when their code is not simple enough ;-)
Do I add comments or not? Should the person reading my code "just learn" how it works? Or should I "just realize" that I am using advanced patterns that few people know?
I think that lists of best practice for comments are mostly irrelevant because most developers simply don't write them.
So, unlike Peter Vogel, I would rather have some bad comments than no comments if that is the price I have to pay for worthwhile comments.
What is it about software development that makes people think that yet another list of things to do will make things better?
If I were to create a rule regarding comments it would be this: code review should include reviewing the comments.
IME people who write bad comments never write worthwhile ones, so that doesn't seem like a tradeoff, unless you mean a binary choice between allowing or forbidding comments.
> If I were to create a rule regarding comments it would be this: code review should include reviewing the comments.
Isn't that usually the case? And it's not that hard. The issue I usually hit is that code review should include reviewing the commit messages, and while others may (I really have no idea) github has even less support for reviewing commit messages than they do PR contents.
It takes a lot of expertise to extract which information (mostly the "why", sometimes a reference you used while coding) is actually useful as a comment.
I also think you need to come across comments that helped _you_ understand other code to learn what good comments are.
Personally,I would rather have well written code than bad comments...and I think programmers can actually create well written code. I question whether we should reasonably expect our programmers, after creating well written code, to suddenly acquire the skillset for writing "worthwhile" comments.
Peter Vogel
Therefore my top advise would be to review comments a few times after writing them to see if they are indeed the breadcrumbs that I hoped they are, or even have someone not involved in the development review the comments for clarity.
When you do git blame you get commit message for each line of code. You can see what ticket changed it (there will be reasons why it changed hopefully), what it was before, what other things changed with it. This is incredibly useful, much more useful than static comments in code. But you have to help yourself by writing good commit messages and making small commits that don't mix many changes into one. If you fix whitespace or some stylistic stuff - don't commit it in the same commit as your business logic changes.
The best things about comments in commit messages is that they are automatically changed when you change a line of code in the next commit. They are never outdated and are never lying to you (regular static comments often do). Git blame should answer "why is each line of code here right now". Static comments answer "what somebody at some point thought was important in this general region of the code".
Often companies want you to adhere to their commit message standards that make it harder to write good commit messages. For example with git they will say "[task number] one line 80 char description"
You can still write a good description and have git show it correctly in one-line format if you do:
[task number] One line 80 char desc.
The rest of a good descriptive commit message.
As many lines as you like....Also, not all code is being read in an IDE, and not all code is stored in git. The code may outlive the repo and valuable context could be lost.
1) I can’t see “git blame” in my code review. Don’t make me check out the branch to review your changes.
2) If we refactor the code (say, extract a new class wrapping the functionality) then the explanation in git becomes much harder to find. If it’s a comment you can just copy it over.
You should explain the change set in your git comments too, but at a different level of abstraction - why is this whole set of changes being made? What problem is being solved? What’s left to do? Etc. this stuff can’t usually be associated with a particular line of code.
So inasmuch as you are arguing for good commit messages I strongly agree. But I disagree that this should be at the expense of good comments in your code.
You shouldn’t need this. The commit message should clearly explain any non-obvious changes (and ideally there should only be one). If there is a historical context, the reviewed commit message should include it (including links to past commits in whatever repo hosting service is used).
> refactor
If there is a refactor the reader can skip past the change in blame. This does become slightly more complicated when code is moved between files, but most repo hosting services make this fairly easy.
The real issue is that code should read like a report as best as humanly possible: it should have a logical structure, be well signposted, local context clear at all times, and easy to spot and correct mistakes.
// NOTE: At least in Firefox 2, if the user drags outside of the browser window,
// mouse-move (and even mouse-down) events will not be received until
// the user drags back inside the window. A workaround for this issue
// exists in the implementation for onMouseLeave().
// TODO(hal): We are making the decimal separator be a period,
// regardless of the locale of the phone. We need to think about
// how to allow comma as decimal separator, which will require
// updating number parsing and other places that transform numbers
// to strings, such as FormatAsDecimal
Long comments disrupt visual flow. No comment is better than a bad comment.
Not necessary and removed code is the best code.
// not a longer comment than thisErm, that's what I said above. I don't believe that's controversial.
And neither is the fact that if there's a 30 line comment above a 100 line function, perhaps the function should be reduced in size because it's clearly complex. In fact, IDEs such as Intellij will flag it for complexity
Commenting for the sake of it, especially due to poorly named functions and variables is a code smell. Code is for the reader. The compiler doesn't care if your variables are two characters or twenty.