4 ms·
But why would you only comment this in the git history? Why on earth wouldn't you place this explanation in a comment preceding the line of code itself? One o
by crazygringo 13y ago
But why would you only comment this in the git history?
Why on earth wouldn't you place this explanation in a comment preceding the line of code itself?
One of the best things I ever learned in programming is that you shouldn't write code to be executed -- you should write code to be read and understood by other people.
It's going to take me forever to read your file and understand what's going on if I have to do a git blame on every other line.
Just use short purpose-based commit messages (fixes a bug where..., so now...), and then put the actual why behind the implementation in the source code comments itself!
- geoka9 13y agoExactly. My problem is that usually the people who neglect to write a comment in the code, also neglect to write meaningful commit messages. Usually it's just "fixed the layout bug" or something like this, along with a bunch of other unrelated changes all squeezed into one commit.
- einhverfr 13y agowhat version control gives you (as a last resort) is a sense of how a change fit into a specific pattern of changes. That's really all you can rely on it for. That's really helpful when trying to track down what broke when, but if it is a routine task, you are in a world of trouble.
- hermannj314 13y agoI concur. I've worked in enterprise. If your team relies on a centrally administered source control, then you can be in a world of pain if the central team decides to switch tools (and when this happens moving your revision history comments to the new system will never be considered important, if even possible). Keep important things in the code. That's my experience.
- salgernon 13y agorcs -> sccs -> cvs -> svn -> git, with a trip through MPW Projector. Half the commit comments lately are "why the hell did git do this to me".
- Roboprog 13y agoAt least you got to skip going through such wonders as Source Safe, ClearCase, MKS Source Integrity or Serena Version Manager. I'm not sure what MPW Projector is, but the rest are pretty mainstream. It's amazing how many proprietary revision control systems there are, and how much worse they are than the free ones. RCS clearly wasn't good enough for a team (distributed or not) or concurrent development, but CVS was good enough, with incremental improvements by SVN & Git. The proprietary systems usually offer integration with a but tracker (mandatory ticket ID on check-in/commit) to lure the ignorant who don't know about commit triggers. Otherwise, they tend to be very slow, frequently time-out their licenses / login-sessions, and/or have a very deficient command line interface making it difficult to script a build system.
- j-kidd 13y agoIn my opinion, the full explanation is too long to be put as code comment, but is just right as the commit message. The best way is to keep the commit message, but add a short comment like: // Hack to trigger layout change in latest Mozilla Then, whoever interested in the hack can read the full explanation from the commit message. Basically, for simple code with unclear purpose, I'd go with short comment in the code plus full explanation in the commit message. For hard-to-read code with complicated logic, I'd go with long comment in the code. Or refactoring. Ticket description, commit message, code comment, and the code itself are all necessary to keep the codebase "documented".
- _delirium 13y agoIf the codebase is associated with a reasonably stable bug-tracker, I'd also put a bug # or a URL in the source comment if it's something nonobvious that is important for future maintainers to be aware of, but considered too long to document inline (if it's purely of historical interest, then yeah, leave it to the VCS history). Or a link to an archived mailing list discussion, or a CVE id, or some kind of hint.
- crazygringo 13y agoI'm genuinely curious -- what is the thinking behind "too long to be put as code comment"? I've never heard that before. It's not like we're conserving paper. And syntax highlighters helpfully give comments different colors so you can skip over them while reading. Personally, I've never once wished that a particular piece of code were less commented, but there are hundreds if not thousands of times I've wished that there was more explanation, or any at all.
- salgernon 13y agoComments are frequently out of date with the code that they're describing. This tendency is somewhat linear with the length if a comment and therefore longer comments will be more incorrect, more quickly. I'm not being facetious, this is a readily observed phenomena.
- einhverfr 13y ago