7 ms·
Another use for comments: to document the strategies you tried and why they failed. In other words not just the "why" but the "why not". Many times I've gone
by crazygringo 5y ago
Another use for comments: to document the strategies you tried and why they failed.
In other words not just the "why" but the "why not".
Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason.
So now I have a new rule: every time I try a simple approach and it fails and I replace it with a more complicated one that works, I add a comment explaining the previous strategy and why it didn't work.
Hilariously, some of these have grown to several failed attempts. "Tried A library but it has a critical bug where B happens. Then tried C function but it also has a bug where D happens. Using external command E doesn't work because F..."
But hey -- neither I nor anyone else will try to reprogram something simpler. Or we can check if the library mentioned still has the bug in question.
- macintux 5y agoI refer to this type of problem a lot when arguing comments are useful. No amount of code can document the code that isn’t there for a reason.
- pmoleri 5y agoOr you can write tests for every single not there case. Just bringing it up, I usually write lots more comments than tests. I also encourage my teammates to add comments. The problem is when one can't really explain why the simpler approach didn't work. That requires more research just to write the comment, but I think it pays off really quick.
- gizmo686 5y ago> The problem is when one can't really explain why the simpler approach didn't work. Another benifit I have found is that in studying the problem to understand why the simpler approach doesn't work, you find out that it can actually work.
- benrbray 5y agoTests are useful, but the big reason that comments are useful is that they are co-located with the relevant code. At the moment, I don't know of any tools that allow you to 1) specify which lines of code are directly relevant to a particular test case, even when the surrounding code changes and 2) see a list of test cases related to the currently highlighted line. I'm sure it would be possible to build such a tool, but the complexity is quite substantial compared to a simple comment or two. If you really want to go the full-test-coverage route it makes a lot more sense to focus that energy on pure/immutable/statically-verified programming rather than some finicky test cases that add substantial maintenance cost to the code.
- dstick 5y agoExactly. And then the question remains: why? Why hate comments so much? I never got that
- rwallace 5y agoI would conjecture that it has two components: 1. Ancestral memory of programming in languages like assembly or early Fortran where your code was going to be spaghetti because the language was capable of little else, so it had to be drenched in comments that would be unnecessary in a better language. 2. Overreaction to personal memory of overzealous professors who demanded assignments be drenched in excessive comments.
- benrbray 5y agoRelated to #2, I'm still recovering from high school AP English. We had to meet quotas for a certain number of underlines / notes written in the margin per page. For the better part of a decade I haven't been able to pick up fiction without the feeling that I'm working through a textbook.
- cush 5y agoUntil the code changes, then the comments are usually worse than nothing
- simonw 5y agoI love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.
- Normal_gaussian 5y agoI find an issue link only works if e is a good enough comment alongside it (ie. Attempting to eliminate this mutex is bug prone, see <link> for archiyectures and their problems).
- bentcorner 5y agoOne caveat with this method is that your source control system evolves and things get archived. Code is around forever but everything around it may change. 10 or 20 years from now your code may still be running, the issue system or the git commit log may not be.
- simonw 5y agoI am fiercely protective of my issue tracker and source history for exactly that reason. I have tools that can grab a full backup should I ever switch to something else: https://datasette.io/tools/github-to-sqlite https://datasette.io/tools/github-to-sqlite
- neolog 5y agoSome people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen. Do you always read the whole git history of a file before editing it? What interface do you use for that?
- simonw 5y agoThe GitHub web interface, specifically the "blame" view for a file.
- ratww 5y agoI also do this with optimisations, when I work on low-level code: If I come up with an inefficient algorithm that's short and readable, I tend to optimise it to something better but leave the reference implementation inside a code block. (This goes without saying, but: I don't leave "commented code", but code inside comment, generally formatted with Markdown)
- Hasnep 5y agoIs there a reason you don't leave a comment with the commit hash of the change instead?
- mjevans 5y agoSome day in the distant future someone will only have a tarball of the source of the last version that worked; if they're lucky. Save that poor sod; have your comments live in your code, not in an SCM system for your code.
- owl57 5y agoGPL has this idea in it: trying to define what exactly should go into that tarball. The question seems meaningful and important even for proprietary code. If some authors assume that anybody modifying their code should be able to look at git commits, that probably simply means that "the preferred form of the work for making modifications to it" is a git repo.
- ratww 5y agoYes, text is better for convenience and for being future-proof. It's like leaving a description of the bug I'm fixing, instead of just a JIRA ticket identifier.
- Nullabillity 5y agoSounds like a good use case for property testing!
- fouc 5y agoIf you have a unit test for that piece of code then that would probably help to act as a stopgap measure against attempting to "fix" the complicated-seeming code.
- SilverRed 5y agoUnit tests have a much bigger chance of being seen as well. There have been a few times where I will write unit tests that don't really test something is working but just check if it has changed. For example there is one table where every time you add or remove a column, you have to make a considered change to another section of the code. Rather than adding a comment saying "hey make sure you change that other section" I have test which lists the columns in the table and fails if they change. Then the person who changed it will see the comment on the test explaining why it failed and what they must do.
- patrick451 5y agoI mean sort of. If the goal of leaving the a comment about the approach that didn't work is to save somebody time before they try that approach again, a regression test is essentially asking the next developer to reconstruct a broken algorithm from thin air based a test. In my opinion, that's close to impossible. So the best case scenario is they re-implement the bad approach and it fails a test. They still wasted a bunch of time that could have been prevented with a simple comment.
- forgotmypw17 5y ago>Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason. >So now I have a new rule: every time I try a simple approach and it fails and I replace it with a more complicated one that works, I add a comment explaining the previous strategy and why it didn't work. My strategy is to comment out the failed attempt and leave it there for next time.
- bombcar 5y ago// // Dear maintainer: // // Once you are done trying to 'optimize' this routine, // and have realized what a terrible mistake that was, // please increment the following counter as a warning // to the next guy: // // total_hours_wasted_here = 42 //
- OnlyMortal 5y agoNot a bad idea.
- bombcar 5y agoMy code would probably be better served by: This place is a message… and part of a system of messages… pay attention to it!Sending this message was important to us. We considered ourselves to be a powerful culture. This place is not a place of honor…no highly esteemed deed is commemorated here… nothing valued is here. What is here is dangerous and repulsive to us. This message is a warning about danger. The danger is in a particular location… it increases toward a center… the center of danger is here… of a particular size and shape, and below us.
- BearfootCoder 5y agoThe inverse of this is also useful: // Dear maintainer, // The code which follows was hacked together under desperate pressure. // It's not smart. // It's not doing anything really subtle. // It's the only thing we could get to work in the time. // If you want to chuck it and replace it, you absolutely should.
- slver 5y agoIt's useful, until you realize you have this on 90% of your code.
- Cthulhu_ 5y agoThat's when a full rebuild can be justified. I'm doing that atm, but I think my predecessor lacked the humility to admit that his code was bad, which is how it went up to 150K of code that basically concatenates XML, converts it to JSON and concatenates HTML on the front-end from the result.
- dzonga 5y agoI use a design doc for this in the style of a append journal. I made this decision a/e/i/o/u based on this and that. the why and the why not. Then I keep appending. easy reference.
- meow112012 5y agonot relevant: I often left comments that helped to explain my situation. One of my last comments: > Resignation letter sent Sometimes code is the only way to love and to talk with... Edited: fix some typo errors