14 ms·

I have the same problem (i.e. terrible short-term memory, though my long-term memory is fine), and I've picked up a number of compensating behaviors over the ye

by timr 4y ago

I have the same problem (i.e. terrible short-term memory, though my long-term memory is fine), and I've picked up a number of compensating behaviors over the years. By far, documentation is my #1 go-to strategy. I document code extensively, even if I'm the only person who is ever going to read it again. People have mocked me for this, but I believe it's a superpower. Most programmers believe a number of blatant falsehoods about documentation, with the most prevalent being "comments go out of date quickly, so there's no point in investing in them". Maybe I'm just hyper-aware of it because my short-term memory sucks, but code comments have saved me on so many occasions that they're simply not optional. You can document your code. You can keep it up to date. It isn't that hard. You just don't want to.

vincnetas 4y ago
If i could i would upvote this 10x times. Always write documentation (especially for your own code). Future you will say thank you to todays you. At least i have done so multiple times. And i always feel cheating my self when i feel lazy to write documentation.
yshrestha 4y ago
I have the same problem. Rather than fight it, use it as your superpower. I find it helps me write easier to understand abstractions because I can't physically hold enough in my head to understand anything more complex. Same is true for documentation!
gleenn 4y ago
If you are diligent about documenting AND updating, sure, seems very reasonable. But most people aren't. You know what the best documentation is? Working tests, much harder to have wrong tests than wrong documentation. Even some of the largest projects like Ruby on Rails have had incorrect internal code docs.
- timr 4y ago
  No. Tests are not documentation. Tests are tests, written in code, which must be explained. You should document your tests, too, because I guarantee the next programmer won't understand your tests as well as you (think you) do. Also: the "next programmer" will be you in a year. This is maybe a close #2 on the list of documentation falsehoods that programmers believe.
  - wizofaus 4y ago
    I wouldn't describe it as a "falsehood that programmers believe", just one of those perhaps unfortunate realities that exist for some codebases that have a decent set of unit tests but little else in the way of up-to-date documentation that explains all edge case behaviour etc. The only documentation you can really trust is that which 100s of others rely on regularly, but a significant percentage of the code most of us work with isn't going to fulfill that criteria.
    - seti0Cha 4y ago
      Explaining edge case behavior is one use-case for comments, and not the most valuable one in my estimation. Aside from that, often incorrect edge case handling is in both the code and the unit test because the problem is that the developer didn't understand the requirements. In my experience, in an undocumented and difficult codebase the tests will be as mysterious or unreliable as the code itself, which makes sense since they are usually written by the same people.
      - wizofaus 4y ago
        You'd be surprised. There are generations of programmers now who think nothing of writing 20+ unit tests with quite clear names demonstrating what the behaviour should be under a variety of conditions, but with virtually no other documentation. Especially true in dev shops that have high coverage requirements for a successful ci build.
  - sodapopcan 4y ago
    Yes. Test _can_ very much be documentation if you write them as such, although they aren't complete documentation. Tests are the specification, ie the the how---documentation provides the why. Test can be written to tell a story but most people aren't taught this way (or simply don't buy it or don't write tests).
    - marcosdumay 4y ago
      No, tests are not specification, they are examples, specifically on the form "do this, and this happens". Imagining a specification out of this is like solving those problems of "what is the next number on this sequence: 1 18 31". It's simply can not be done, you can guess something, but you will never know if it's the real answer.
- twobitshifter 4y ago
  Show me a set of tests that I can use to build something more easily than using the documentation? It sounds like just kicking the can down the road to the next person.
- layer8 4y ago
  Tests may describe the what, but they don’t explain the why and the how, which are the important parts.
- jjav 4y ago
  > You know what the best documentation is? Working tests Tests do have a slight overlap with documentation, but it's that, only slight. If a piece of code has some weird non-obvious behavior, the presence of a test for that particular behavior is a signal that it's actually intentional, not a random bug. But, it doesn't tell me anything why that design choice happened. That's what the documentation is for. So facing such code, I sure hope it's well documented.
- JohnBooty 4y ago
  Tests verify what the code is doing. And I agree: they are a great source of insight when understanding an unfamiliar codebase. However, comments are typically better at answering the why. If you are diligent about documenting AND updating I don't understand why this is viewed as challenging. Writing a sentence or two here and there is orders of magnitude easier than writing the code itself. And any code review process should help to prevent situations where the code and comments are out of sync. Lastly, I feel like there's a larger human issue. I write comments to explain certain why's in the code because I care about my teammates and I care about the project. If others don't do the same, I think it speaks to a lack of care for their fellow engineers and the work itself. I think, "I just spent five hours figuring out something that you could have explained with a single 30-second comment?" I'm baffled that some engineers think that this is okay.
psygn89 4y ago
I agree it's a lame excuse not to document code, however there are just some parts that just changes way too often by multiple people where outdated comments can actually lead you astray. The stuff I touch doesn't change often so I'll comment to explain the weird and ambiguous looking parts.
- timr 4y ago
  I'm not saying you have to document each line of code with equal rigor. In fact, there's an art to knowing what to document, and like most arts, you get better at it over time. Sometimes I feel silly about what I've documented and what I've neglected, but that's OK. I learn. The "code changes way too often" excuse is basically a restatement of the myth that I wrote above. Yes, code changes over time. It's pretty easy to change the comment with the code, when necessary. The team members who don't do this aren't doing their jobs. But at the end of the day, even if code deviates from comments that's still fine. Having an outdated, well-written comment is a historical record of what the code was supposed to be doing. That's useful.
redkoala 4y ago
Is there a solution for this problem in real-life?
- layer8 4y ago
  Write things down. Use reminders. Place things where you will notice them when you need to be reminded of them, like the proverbial string tied around your finger.
- lhuser123 4y ago
  There are some “tricks”. For example blending what you want to remember with something memorable, creating a mental picture & recall it a few times. That’s what I got from the book Moon Walking with Einstein.
seti0Cha 4y ago
I'm in exactly the same position. My memory is awful so I write notes to my future self. It's not hard to keep comments up to date if you keep them near the code and don't use a lot of boilerplate.
- timr 4y ago
  > It's not hard to keep comments up to date if you keep them near the code and don't use a lot of boilerplate. Yep, exactly. It only gets "complicated" when you start having these heavy-handed doc generators that are parsing your code and breaking the build. I feel pretty strongly that sphinx, rubydoc, python docstrings et al. are fine tools, but you have to have a light touch with how they're applied. Autogenerated external docs are a separate problem, and shouldn't discourage developers from commenting their code.
mgaunard 4y ago
Code is already a formal specification of what the machine is set to do. All your documentation can do is make it more ambiguous. Usually the documentation is wrong as well, but that might be because the programmer didn't know how to specify clearly what he wanted.
- timr 4y ago
  > Code is already a formal specification of what the machine is set to do. I take back my other comment where I said that "tests are documentation" is the #2 falsehood about documentation that programmers believe. This is the #2 falsehood. Yes, "formally" the code is the spec. That doesn't help you very much though, squishy human, because you're not a computer.
  - mgaunard 4y ago
    Competent programmers should know all the fine details of the programming language they work in, in effect being human compilers.
    - jodrellblank 4y ago
      if this is a useless comment: // set i to 1 int i=1; and this is a useful comment: // there is a method overload which accepts an array, // but it's buggy and crashes. workaround: cast to tuple first. ... then you seem to be assuming people only want to write and read the first kind. Because no matter how well you 'know all the fine details of the programming language', comments can tell you things the code can't. Even aside from the pointless gatekeeping of "competent programmers" - ok what about people who aren't employed as programmers but still need to read and write code? What about the people who just have to deal with it being an unfamiliar language because nobody who knows the language is available?
      - 8note 4y ago
        Is that a useful comment? Seems more like a check style entry. That comment will apply to every time the overload is available, not for this instance of the call
bityard 4y ago
I think some people have run into a few cases where the documentation is stale, and then reflexively generalize that to "all documentation is stale." And that's patently absurd on the face of it.
- closeparen 4y ago
  Depending on the nature of your memory and thought process, the insights gained from potentially-false statements in the documentation when they are true might be outweighed by the blind alleys and misunderstandings generated when they are false. You'd have to be very good at remembering where things came from and tagging them with their level of certainty. An important skill! But not a trivial one.
  - Jensson 4y ago
    > You'd have to be very good at remembering where things came from and tagging them with their level of certainty. I wonder why not more people do this? Not just for code, but for everything. I remember where I learned everything I know, I don't trust anything unless I remember the source. How do other people think, do they think that whatever pops up in their head is the truth without any source? Then how do they know it is a fact and not just a hunch or a guess?
  - sgc 4y ago
    It would be neat if your code editor could easily highlight the code newer than the comment(s) and tests based on your git history (without jumping out of your work, of course). Even something as simple as "highlight all code newer than the current line", for example, would be quite useful.
- hinkley 4y ago
  Docs don't go stale like bread. They atrophy from disuse. I always force the onboarding process to go through our docs, and I spend a little time with each new person observing their progress looking for regressions in the docs. You can't get that with old-timers because of the echo chamber/curse of knowledge effect. This breaks down when you have a place that never hires new people. And rather than thinking that's a flaw in my process, I'm starting to think that's a flaw in the business itself. Without fresh ideas and feedback a project stagnates.
BerislavLopac 4y ago
Of course comments stay in sync with the code... if you're the only one working on that code. As soon as you have multiple developers, you can forget about it.
- nso95 4y ago
  Treat comments the same as code when you review PRs
- jjav 4y ago
  > As soon as you have multiple developers, you can forget about it. That's only true if everyone can check in code willy-nilly without any approval. If you require code reviews then that's just part of the code review. No documentation update = no approval, just like missing tests or bad code.
- hutzlibu 4y ago
  "Of course comments stay in sync with the code... if you're the only one working on that code." If I am in a rush to implement something and then am sidetracked because of a stupid small bug, then I just fix that small bug in the code. And then another one. In these states I only pay attention to code, and not text. If I would also have to read the text, then I would forget the original task. So sadly no, comments do not automatically stay in sync with code for me, unless I put in the extra effort of cleaning up afterwards.
  - ParetoOptimal 4y ago
    > If I am in a rush to implement something and then am sidetracked because of a stupid small bug, then I just fix that small bug in the code. What if the small bug that side-tracked you eould have been prevented by a comment?
    - hutzlibu 4y ago
      What if the small bug got introduced because of lack of time to cater all the verbose comments? But seriously, in the cases I remember - not really. Most bugs are a cause of lack of higher level understanding of a certain module. Some clear comments can help with that, but better is proper higher level documentation and the time to read and maintain them.
babyshake 4y ago
> Most programmers believe a number of blatant falsehoods about documentation, with the most prevalent being "comments go out of date quickly, so there's no point in investing in them". More broadly, a problem with our cognition is that when we remember something right now, we often think it is unlikely or even not possible that we wouldn't remember it a day, a week, a month from now.
- hutzlibu 4y ago
  Oh yes, that is a lesson I also learned the hard way. Solution: documenting, taking notes and organising it all.
abstractbill 4y ago
This is funny to me because we seem to be complete opposites! I have a great short-term memory, but my long-term memory is sadly completely trashed. I don't care if someone wants to document their code, but I never actually trust that documentation to be accurate or up-to-date. I expect it to be misleading and time-wasting, and so I only trust the code itself. I personally only write comments for bits of code that I find confusing, and I think it's a bit of a failing when I have to do that -- I'd much prefer to put in the extra time and effort to rewrite the code to not be confusing. (I don't write code for a living these days btw, only for myself. It's much more fun, and I get to not care anymore whether other people think I'm wrong about things like these).
- tharkun__ 4y ago
  This so much. I really don't trust most comments at all. I think we also need to be explicit about the kind of comment. There are comments that are categorically always bad. These are the "this code does X" kind of comments. Those go out of date really quickly in a shared code base. They don't even make sense for myself on a project I'm doing myself. The code should read like the comment would. Almost like prose. If it doesn't, I haven't made the code good enough yet. We no longer live in a world where the code needs to only be machine readable and unreadable to most mortals. We have the luxury of being able to use good abstractions and extract functions without worrying about code running slow because of too many indirections, stacks that are too big etc. We can optimize for direct code readability! Then there are the "why" comments. Those can be invaluable. If I assume I have the kind of good code I can just read as to the "what is this doing", I can sparingly add information to things that might seem unusual or weird or inexplainable. Same with tests mentioned in some sibling posts. Tests should be written in a self documenting way. I like to name my tests after what they're testing. Like "should behave in X manner when doing Y to Z" from a user's point of view, not on a technical level. User not necessarily meaning end user, say if you're testing an API or library function. Different language make this easier or harder but I do it in all of them. Armed with that documentation of what my tests pre-requisites are and what the expected outcome is, I can write the actual test. I should be able to deduce the expectations of the test from the test's "name", thus double checking that I am testing the correct thing. Many tests I find in shared code bases are utterly unreadable, have way too many expectations and side effects and test too many things at once. With the above technique there's usually only one or very few expectations. If I parsed out the test names from all my tests and just gave them to you as a document, it should almost read like a documentation of all of the expected behaviors of my piece of software.
hinkley 4y ago
We have some blatant falsehoods about how documentation should be organized as well. Virtually everyone seems to think that people know which file to open, and so we organize files as if the person is always in the right place. This doesn't scale, because as the size of the project and the number of docs increases, we start refining generic knowledge into more refined slices of the problem domain. At first the docs are so far apart that you rarely miss, but as time goes you miss more and more. So while your outline might suggest that finding docs grows logarithmicly, it's linear at best. The first line of any doc should answer "where am I?" and "why do I care" because the odds that they don't care go up over time, and people put a time limit on self-service. After 2-3 wrong pages in a row they start getting impatient, unless they got through those wrong pages in 5 seconds apiece.
amalcon 4y ago
"Comments go out of date quickly" is true -- it's the "there's no point in investing in them" that's incorrect. In addition to being valuable in the short term (to both you and anyone else who ends up looking at the code), "comment just became outdated" is a highly valuable signal that a prior assumption made by other code could now be false, and you should look into that.
- gregmac 4y ago
  I have worked on teams where the code is very well documented (basically every public method, parameter, property or class gets a comment) and it's not at all hard to keep up to date. Sometimes people forget, but when you look at a PR and see the usage or meaning has changed with no corresponding comment change, it's easy to flag.
treeman79 4y ago
I used to have an amazing working memory. Could keep a dozen things in mind at once. Or context switch fast enough to be the same effect. Had a series of strokes. Mostly recovered but now short term memory is one thing at time. I have leaned to document like crazy as I’m working. Todo lists are my life now.
zelphirkalt 4y ago
Usually when writing some code, which deals with something new for me, I get many "idiot questions" in my head. I try to write comments in a way, which will answer my future self's "idiot questions". Answering all those questions, I feel more like I truly understand, what I am doing.
- arithma 4y ago
  I often don't comment code, especially in personal stuff, but when I occasionally do, which happens mostly when things get overwhelming, I find bugs or fix things that I was stuck on. Writing forces you to understand better, name better, and almost feels like providing you with another perspective, all without leaving your own self.
SkyMarshal 4y ago
One way to cap the cognitive load of adding and maintaining comments is to limit them to explain why a piece of code does what it does, rather than how. Rely on the fact that the how is self-documenting to other programmers who may need to maintain your code later (including you), but the why is not always so. Eg, were other options considered and this one chosen? Why? Is this piece of code non-standard or particularly clever? Why? Is this piece of code more complex than it seems like it needs to be? Why? Does this piece of have non-local dependency that may not be obvious at first glance? Are there security concerns with this piece of code which are non-obvious to a novice or an outsourced worker? Etc. There's the old saying, "since debugging code is more difficult than writing it, then if you write the most clever code you are capable of, then you are by definition incapable of debugging it". Pretend you're explaining your code to future you who has forgotten why you did what you did and isn't clever enough to debug it.
- fishtoaster 4y ago
  I think "why" comments are the most useful, but "what" comments are a bit undervalued. A few types of "what" comments are, I find, very useful: 1. Comments that are effectively headers: # If the user is foobar, do thing user = User.find(current_user_id) user.preload_bizbaz!(cache: false) is_foobar = user.bizbaz.foobar.status == "yes" if (is_foobar) { do_thing(user) } Yes, you can read the 4 lines of code to see the "what' - the comment is duplicative. But when I'm skimming through a large codebase trying to find or understand something, these headers can be invaluable. 2. Comments on dense code # Matches any email like foo@bar.com (only .com, .net, .org email addresses) return email.match(/^.*@.*\.(com|net|org)$/) Yes I can that regex, but I can read that comment a lot faster.
  - vikingerik 4y ago
    And the latter is a perfect example of what goes wrong, when someone adds "gov" to the regex but doesn't notice the comment to update it.
    - Arrath 4y ago
branko_d 4y ago
I practice something I could only describe as “comment-driven development”. Whenever I need to implement something non-trivial, something that might have subtle edge cases or has to be done in a certain way because of the external dependencies, I first write the comment before writing the code. I might iterate on the comment, not unlike one might iterate on a design document, and basically use it as a mental tool to fully understand the details of what needs to be done. After I do that, I use the comment to remind me about all these details as I go through the implementation. All this is doubly important when designing an API, where the comment (also) serves as the externally visible documentation for that API. It helps me put myself into the shoes of the caller reading that documentation without knowing the implementation details, which I believe helps me design a better API. I hear that “comments go out of date” a lot, but in my case, if a comment doesn’t match the code, it’s usually the code that needs fixing.
- dotancohen 4y ago
  I do the same thing. I then replace the comment with a method name that describes exactly what the comment described, e.g. _getLowestFooIdFromBarCollection(). I then implement the code inside this private method.
  - rlayton2 4y ago
    Similar to my strategy. Write the code as if I had all these magic functions that did steps: def write_report(): db = connect_to_database() data = get_data(db) summary = summarise_data(data) save_report(summary) After this, do the same for each of these functions.
    - adolph 4y ago
      I do pseudo code sometimes too. I notice that your functions/methods/whatever are verbs that are assigned to nouns. It reminds me of: Verbs in Javaland are responsible for all the work, but as they are held in contempt by all, no Verb is ever permitted to wander about freely. If a Verb is to be seen in public at all, it must be escorted at all times by a Noun. http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-nouns.html http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom...
daotoad 4y ago
We need to write code that is optimized for communication and clarity. We have a number of tools we can use to craft communicative code. 1. Variable and function names. These should be descriptive and never deceptive. For example, I've seen metric tons of code like this `const json = makeSomeApiCall(params)` where the contents of `json` is a the decoded response data and not a JSON string. This code is deceptive and obfuscatory. But if you write `const decodedFooResponse = makeSomeApiCall(params);` then you are accurately describing what the value is. This is particularly import in untyped/loosely typed languages where the value of the variable could be anything. 2. Code structure and layout. When writing prose, we achieve clarity through structure. Code is no different. Keep related things together. Avoid run-ons. In other words, write code that has smallish functions, with smallish interfaces, it's easier to reason about how the code will behave. Avoid unnecessary mutation of values--repeated mutation of the same value is particularly pernicious. Use white space to create visual separations of distinct ideas. Use abstraction and encapsulation to keep code focused. Avoid deeply nested conditionals, flattening the tree whenever possible. And a million other strategies that can all help. 3. Tests. Tests can be documentation, but they certainly aren't always. They also aren't convenient documentation--what they offer isn't going to show up in your editor when you inspect a method. Unit tests are a nice way of recording verifiable expectations for behavior. But if the test code is complicated or poorly organized, all it does is compound the misery of working on a messy codebase. 4. Comments are distinct from documentation here. Comments are little side notes like "this implementation is a bit of a hack. It is brittle because .... but we decided to keep it because X. See someURL for contemporaneous discussion." They tell us why a thing is the way it is or about some sort of risk or unexpected detail. 4. Documentation is absolutely a part of making code understandable. These docs are primarily going to be used in an IDE/editor when viewing function signature data. Ideally you can write JavaDoc/TSDoc/POD or similar inline docs. Examples are worth their weight in gold. We should be using all our tools to write communicative code. We don't need every technique for every line or block, but over the scope of a package or project, we should judiciously employ them all. Every line added comes with a concomitant maintenance cost--we must ensure that every line we add is worth that cost.
- jarjoura 4y ago
  This should be the top reply! Just want to add my extra take on comments: Comments are absolutely necessary when explaining complex logic that is hard to read for the casual reader (or yourself 6 months later). Comments are not necessary when the code itself explains what it does by being clearly named, isolated and organized. Comments are not documentation and shouldn't be used as such. They are tools to improve code clarity for the person who is changing the code. They are not tools for someone who is using the code. If the intent is to teach someone what the code does so they can use it somewhere else, write documentation in a wiki with examples and link the wiki URL to that point in the code.
suprjami 4y ago
This reminds me of an anecdote about code which was always beautifully commented. The author would code while wasted and couldn't remember anything if it wasn't on the page in front of them, hence the comments.
r24y 4y ago
One thing that I believe is under-documented in code is _business decisions_. The team arrives at a decision in a meeting or informal discussion, and it leads to some code that might be tough to understand without context. I'll usually add a comment briefly describing the decision, and initial and date it. Initially I would just link to a wiki page in a comment, but occasionally these links break, so in my experience it's better to include the notes directly.
- Archelaos 4y ago
  It is often also useful not only to document the decision the team arrives at, but also briefly write down what was decided not to implement and why. This is very helpful when people come in a few weeks later with a "new" idea that has already been discussed, or in onboarding new people to the project.
- tcoff91 4y ago
  The commit message should contain all the unusual context needed to understand the change. In practice however, most people write terrible commit messages.
  - ParetoOptimal 4y ago
    Many never even use multi-line commit messages.
  - bornfreddy 4y ago
    It's not just that. Commit messages have a property that they get overwritten. When I refactor some code for performance reasons, I don't want to remove documentation - which is exactly what happens if I make a commit. True, older commit messages are available in the history, but... not conveniently available.
  - conradfr 4y ago
    And ideally the id of the ticket associated to the code change.
stavros 4y ago
I feel like many people take the "comments will go out of date" adage the wrong way. To me, it doesn't say "don't write comments", it says "give your comments some love while you code". It's meant to warn against letting comments become false, not against writing them. To me, at least.
tayo42 4y ago
> You can document your code. You can keep it up to date. It isn't that hard. You just don't want to. Yeah I can or an individual can, that misses the point of the advice which is intended for groups on large projects with deadlines. Like once a manager says get this done now and we'll find time later for the rest... That never happens
bee_rider 4y ago
I have a similar issue. I ended up pretty good at math; had to re-derive everything every time.
justbaker 4y ago
>You can document your code. You can keep it up to date. It isn't that hard. You just don't want to. YES
foerbert 4y ago
Same issue here. It's one of the reasons I've become so enamored with Ada. With Ada, it's not only easy, but encouraged, to encode so much information in about how things are modeled into the program itself. Not only does it function somewhat like documentation, it also lets the compiler helpfully yell at me when I still manage to forget how things actually work. It's saved me so much stress and debugging time. Now if only any of these 'safer' languages would add even just strong typedefs. Even if they don't particularly encourage their use, it'd be something.
baby 4y ago
Oh gosh, this 100 times. I comment everything, even rationale behind decisions, I'm recently writing a book as I write a compiler[1] because some parts are confusing me so much that I just can't solve them, and can't go back to work on them later, if I don't document them. Even if things go out of date, it does not matter, because it still is somewhat close to what used to be there and can still help the future reader (me or someone else) figure out what might have happened since then. It's a million times better than no documentation. [1]: https://mimoo.github.io/noname/ https://mimoo.github.io/noname/
- throwawaylinux 4y ago
  Changelogs are very good for that if you write good changesets. They don't go out of date either, because you know exactly what source they apply to.
  - baby 4y ago
    I feel like nobody goes to look at changelogs, or PRs, or commits. Probably because they don't ever expect anything good from it. Also they're not really searchable.
    - jlokier 4y ago
      It depends on the project. Linux kernel commits often have excellent messages, because that's the standard expected.
      - baby 4y ago
        But still, how would you search through commit history to figure out one thing? Comments are right here in the code, and books/external doc/rfcs refer to concepts. I feel like commits are only good if you're spelunking, which is usually for a single reason: you're bisecting looking for a bug.
        jlokier 4y ago
dllthomas 4y ago
> You can document your code. You can keep it up to date. It isn't that hard. You just don't want to. Documentation that is close to the things it is talking about isn't hard to keep up to date. What is hard is knowing, when I make a change here, that someone (maybe me) talked about this thing over there without any pointer from here to there. Can I do a careful search of everywhere there might be documentation every time I make a change? Yeah, I guess; it'll definitely slow me down in the short term and I'll still miss things.
- andirk 4y ago
  Does "documentation" mean separate documents completely disconnected to the codebase? Isn't that the problem? Code gets updated according to necessity whereas documentation is for human consumption and not required to make the thing work.
  - dllthomas 4y ago
    > Does "documentation" mean separate documents completely disconnected to the codebase? At worst, yes. I've increasingly seen docs in Notion, but Confluence was common before and probably still is. I agree that a big part of the solution is "get it all in the repo" but I don't think that's enough. Even within a repo, writing can be pretty distant from the code it discusses. In my experience, programmers and reviewers are great about comments on or adjacent to changed lines (not coincidentally, what shows up in git diff and code review software). Both are still pretty good about comments that they can structurally expect to be present, like function documentation at the top of a function. It falls off a lot for programmers when it's a comment talking about something more than maybe 20 lines away, whether that's a quick sketch at the top of a loop or a block comment somewhere in the file about invariants or caveats or gotchas. At that point, reviewers simply will not catch that the programmer didn't update the documentation, unless they happen to be unusually familiar with the file in question. Comments that reference code in other files are thankfully rare if you have reasonable modularity, but will also be missed by both programmer and reviewer unless the task in question touches both files in a relevant way. Documentation in the repository that is not a part of code is hit and miss. Developer setup guides are often brittle to particular system configurations, but usually get some effort every time the new hire trips over something. Runbooks similarly, and less limited to the new hire, and hopefully you look them over proactively on occasion. Large scope architecture documents are doomed; I am more optimistic about something like ADRs which should be relatively narrow and aren't intended to be updated beyond deprecation. Much of this can be helped with tooling, but where it exists its poorly standardized.
ryan-allen 4y ago
I (should better maintain) my little compendium of shell 'one liners' that do all sorts of incredibly useful things, that getting right first time, were hard won. Having that handy you can seem like a god at times to your colleagues when they are trying to solve something. "Oh, did you know you can do this? I'll message it to you." I think my working memory isn't very good, but there is something in there that is very good surely, because how else would I have been able to computers for this long?
softfalcon 4y ago
The added bonus to writing good comments is you’re practicing technical writing directly associated with your code. It’s similar to writing your own flash cards, but by rephrasing the code into a comment you’re visually and linguistically using a form of repetition to stick the code inside your head with a human readable explanation. This can make you a better technical communicator when discussing any code with others. There is a lot more than “I will read this comment in 6 months and it will save my ass” going on when you practice writing good comments. I really like this because in my opinion, half of my job is good communication, another quarter is planning/design, and the final quarter is actually writing code.
keyle 4y ago
In a world where comments are terse; if it takes longer to grok the code than it takes to read a comment, the comment is worthwhile. // this does x do_x() is a bad comment, however... // this does x OMG_WTF_function_call(rocket science maths & bitmask); is a good comment :)
gernb 4y ago
IMO there is some common sense to comments that is often not followed. Example: I work on a project that has a pre-submit script that requires comments for tests. This leads to ridiculousness where I have code like // Test that uploading data with XYZ function works TEST(UploadingDataWithXYZFuncWorks) { ... } Like WTF! The function name says all that needs to be said. There are is no more info needed but I had to appease some over zealous programmer. Meanwhile, in an existing test in the same file I see code like this // Set the dimensions SetDimensions(0, 0, width, height) Again, WTF! Comments are important for explaining why something exists, what its assumptions are, edge cases, etc..., but you can also go overboard with comments and you can make your code more readable by using readable names for functions and variables.
sooyoo 4y ago
> "comments go out of date quickly, so there's no point in investing in them" The key difference is where the described thing lives. A comment describing the next few lines of code or some loop that follows, or similar, won't go out of date since it's easily updated together with what it describes. A comment living in another file, describing loosely some far-reaching but still-evolving aspect will likely be outdated soon, if the thing it describes changes and that comment is out of sight and needs extra effort to be remembered and updated.
Cthulhu_ 4y ago
That said, walls of texts may not get read. I write walls of text, but I'm sure nobody reads them, not even me :D
ducharmdev 4y ago
Can I work with you? Joking aside, documenting as a habit alongside coding is like a superpower. I find that writing can act as validation against my understanding of a problem; if I struggle to write about it, then it's likely that I don't understand the problem as well as I thought.
HeavyStorm 4y ago
YES! That argument is so stupid. Just do the work.

by timr 4y ago

vincnetas 4y ago

If i could i would upvote this 10x times. Always write documentation (especially for your own code). Future you will say thank you to todays you. At least i have done so multiple times. And i always feel cheating my self when i feel lazy to write documentation.

yshrestha 4y ago

I have the same problem. Rather than fight it, use it as your superpower. I find it helps me write easier to understand abstractions because I can't physically hold enough in my head to understand anything more complex. Same is true for documentation!

gleenn 4y ago

If you are diligent about documenting AND updating, sure, seems very reasonable. But most people aren't. You know what the best documentation is? Working tests, much harder to have wrong tests than wrong documentation. Even some of the largest projects like Ruby on Rails have had incorrect internal code docs.

timr 4y ago
No. Tests are not documentation. Tests are tests, written in code, which must be explained. You should document your tests, too, because I guarantee the next programmer won't understand your tests as well as you (think you) do. Also: the "next programmer" will be you in a year. This is maybe a close #2 on the list of documentation falsehoods that programmers believe.
- wizofaus 4y ago
  I wouldn't describe it as a "falsehood that programmers believe", just one of those perhaps unfortunate realities that exist for some codebases that have a decent set of unit tests but little else in the way of up-to-date documentation that explains all edge case behaviour etc. The only documentation you can really trust is that which 100s of others rely on regularly, but a significant percentage of the code most of us work with isn't going to fulfill that criteria.
  - seti0Cha 4y ago
    Explaining edge case behavior is one use-case for comments, and not the most valuable one in my estimation. Aside from that, often incorrect edge case handling is in both the code and the unit test because the problem is that the developer didn't understand the requirements. In my experience, in an undocumented and difficult codebase the tests will be as mysterious or unreliable as the code itself, which makes sense since they are usually written by the same people.
    - wizofaus 4y ago
      You'd be surprised. There are generations of programmers now who think nothing of writing 20+ unit tests with quite clear names demonstrating what the behaviour should be under a variety of conditions, but with virtually no other documentation. Especially true in dev shops that have high coverage requirements for a successful ci build.
- sodapopcan 4y ago
  Yes. Test _can_ very much be documentation if you write them as such, although they aren't complete documentation. Tests are the specification, ie the the how---documentation provides the why. Test can be written to tell a story but most people aren't taught this way (or simply don't buy it or don't write tests).
  - marcosdumay 4y ago
    No, tests are not specification, they are examples, specifically on the form "do this, and this happens". Imagining a specification out of this is like solving those problems of "what is the next number on this sequence: 1 18 31". It's simply can not be done, you can guess something, but you will never know if it's the real answer.
twobitshifter 4y ago
Show me a set of tests that I can use to build something more easily than using the documentation? It sounds like just kicking the can down the road to the next person.
layer8 4y ago
Tests may describe the what, but they don’t explain the why and the how, which are the important parts.
jjav 4y ago
> You know what the best documentation is? Working tests Tests do have a slight overlap with documentation, but it's that, only slight. If a piece of code has some weird non-obvious behavior, the presence of a test for that particular behavior is a signal that it's actually intentional, not a random bug. But, it doesn't tell me anything why that design choice happened. That's what the documentation is for. So facing such code, I sure hope it's well documented.
JohnBooty 4y ago
Tests verify what the code is doing. And I agree: they are a great source of insight when understanding an unfamiliar codebase. However, comments are typically better at answering the why. If you are diligent about documenting AND updating I don't understand why this is viewed as challenging. Writing a sentence or two here and there is orders of magnitude easier than writing the code itself. And any code review process should help to prevent situations where the code and comments are out of sync. Lastly, I feel like there's a larger human issue. I write comments to explain certain why's in the code because I care about my teammates and I care about the project. If others don't do the same, I think it speaks to a lack of care for their fellow engineers and the work itself. I think, "I just spent five hours figuring out something that you could have explained with a single 30-second comment?" I'm baffled that some engineers think that this is okay.

psygn89 4y ago

I agree it's a lame excuse not to document code, however there are just some parts that just changes way too often by multiple people where outdated comments can actually lead you astray. The stuff I touch doesn't change often so I'll comment to explain the weird and ambiguous looking parts.

timr 4y ago
I'm not saying you have to document each line of code with equal rigor. In fact, there's an art to knowing what to document, and like most arts, you get better at it over time. Sometimes I feel silly about what I've documented and what I've neglected, but that's OK. I learn. The "code changes way too often" excuse is basically a restatement of the myth that I wrote above. Yes, code changes over time. It's pretty easy to change the comment with the code, when necessary. The team members who don't do this aren't doing their jobs. But at the end of the day, even if code deviates from comments that's still fine. Having an outdated, well-written comment is a historical record of what the code was supposed to be doing. That's useful.

redkoala 4y ago

Is there a solution for this problem in real-life?

layer8 4y ago
Write things down. Use reminders. Place things where you will notice them when you need to be reminded of them, like the proverbial string tied around your finger.
lhuser123 4y ago
There are some “tricks”. For example blending what you want to remember with something memorable, creating a mental picture & recall it a few times. That’s what I got from the book Moon Walking with Einstein.

seti0Cha 4y ago

I'm in exactly the same position. My memory is awful so I write notes to my future self. It's not hard to keep comments up to date if you keep them near the code and don't use a lot of boilerplate.

timr 4y ago
> It's not hard to keep comments up to date if you keep them near the code and don't use a lot of boilerplate. Yep, exactly. It only gets "complicated" when you start having these heavy-handed doc generators that are parsing your code and breaking the build. I feel pretty strongly that sphinx, rubydoc, python docstrings et al. are fine tools, but you have to have a light touch with how they're applied. Autogenerated external docs are a separate problem, and shouldn't discourage developers from commenting their code.

mgaunard 4y ago

Code is already a formal specification of what the machine is set to do. All your documentation can do is make it more ambiguous. Usually the documentation is wrong as well, but that might be because the programmer didn't know how to specify clearly what he wanted.

timr 4y ago
> Code is already a formal specification of what the machine is set to do. I take back my other comment where I said that "tests are documentation" is the #2 falsehood about documentation that programmers believe. This is the #2 falsehood. Yes, "formally" the code is the spec. That doesn't help you very much though, squishy human, because you're not a computer.
- mgaunard 4y ago
  Competent programmers should know all the fine details of the programming language they work in, in effect being human compilers.
  - jodrellblank 4y ago
    if this is a useless comment: // set i to 1 int i=1; and this is a useful comment: // there is a method overload which accepts an array, // but it's buggy and crashes. workaround: cast to tuple first. ... then you seem to be assuming people only want to write and read the first kind. Because no matter how well you 'know all the fine details of the programming language', comments can tell you things the code can't. Even aside from the pointless gatekeeping of "competent programmers" - ok what about people who aren't employed as programmers but still need to read and write code? What about the people who just have to deal with it being an unfamiliar language because nobody who knows the language is available?
    - 8note 4y ago
      Is that a useful comment? Seems more like a check style entry. That comment will apply to every time the overload is available, not for this instance of the call

bityard 4y ago

I think some people have run into a few cases where the documentation is stale, and then reflexively generalize that to "all documentation is stale." And that's patently absurd on the face of it.

closeparen 4y ago
Depending on the nature of your memory and thought process, the insights gained from potentially-false statements in the documentation when they are true might be outweighed by the blind alleys and misunderstandings generated when they are false. You'd have to be very good at remembering where things came from and tagging them with their level of certainty. An important skill! But not a trivial one.
- Jensson 4y ago
  > You'd have to be very good at remembering where things came from and tagging them with their level of certainty. I wonder why not more people do this? Not just for code, but for everything. I remember where I learned everything I know, I don't trust anything unless I remember the source. How do other people think, do they think that whatever pops up in their head is the truth without any source? Then how do they know it is a fact and not just a hunch or a guess?
- sgc 4y ago
  It would be neat if your code editor could easily highlight the code newer than the comment(s) and tests based on your git history (without jumping out of your work, of course). Even something as simple as "highlight all code newer than the current line", for example, would be quite useful.
hinkley 4y ago
Docs don't go stale like bread. They atrophy from disuse. I always force the onboarding process to go through our docs, and I spend a little time with each new person observing their progress looking for regressions in the docs. You can't get that with old-timers because of the echo chamber/curse of knowledge effect. This breaks down when you have a place that never hires new people. And rather than thinking that's a flaw in my process, I'm starting to think that's a flaw in the business itself. Without fresh ideas and feedback a project stagnates.

BerislavLopac 4y ago

Of course comments stay in sync with the code... if you're the only one working on that code. As soon as you have multiple developers, you can forget about it.

nso95 4y ago
Treat comments the same as code when you review PRs
jjav 4y ago
> As soon as you have multiple developers, you can forget about it. That's only true if everyone can check in code willy-nilly without any approval. If you require code reviews then that's just part of the code review. No documentation update = no approval, just like missing tests or bad code.
hutzlibu 4y ago
"Of course comments stay in sync with the code... if you're the only one working on that code." If I am in a rush to implement something and then am sidetracked because of a stupid small bug, then I just fix that small bug in the code. And then another one. In these states I only pay attention to code, and not text. If I would also have to read the text, then I would forget the original task. So sadly no, comments do not automatically stay in sync with code for me, unless I put in the extra effort of cleaning up afterwards.
- ParetoOptimal 4y ago
  > If I am in a rush to implement something and then am sidetracked because of a stupid small bug, then I just fix that small bug in the code. What if the small bug that side-tracked you eould have been prevented by a comment?
  - hutzlibu 4y ago
    What if the small bug got introduced because of lack of time to cater all the verbose comments? But seriously, in the cases I remember - not really. Most bugs are a cause of lack of higher level understanding of a certain module. Some clear comments can help with that, but better is proper higher level documentation and the time to read and maintain them.

babyshake 4y ago

> Most programmers believe a number of blatant falsehoods about documentation, with the most prevalent being "comments go out of date quickly, so there's no point in investing in them". More broadly, a problem with our cognition is that when we remember something right now, we often think it is unlikely or even not possible that we wouldn't remember it a day, a week, a month from now.

hutzlibu 4y ago
Oh yes, that is a lesson I also learned the hard way. Solution: documenting, taking notes and organising it all.

abstractbill 4y ago

This is funny to me because we seem to be complete opposites! I have a great short-term memory, but my long-term memory is sadly completely trashed. I don't care if someone wants to document their code, but I never actually trust that documentation to be accurate or up-to-date. I expect it to be misleading and time-wasting, and so I only trust the code itself. I personally only write comments for bits of code that I find confusing, and I think it's a bit of a failing when I have to do that -- I'd much prefer to put in the extra time and effort to rewrite the code to not be confusing. (I don't write code for a living these days btw, only for myself. It's much more fun, and I get to not care anymore whether other people think I'm wrong about things like these).

tharkun__ 4y ago
This so much. I really don't trust most comments at all. I think we also need to be explicit about the kind of comment. There are comments that are categorically always bad. These are the "this code does X" kind of comments. Those go out of date really quickly in a shared code base. They don't even make sense for myself on a project I'm doing myself. The code should read like the comment would. Almost like prose. If it doesn't, I haven't made the code good enough yet. We no longer live in a world where the code needs to only be machine readable and unreadable to most mortals. We have the luxury of being able to use good abstractions and extract functions without worrying about code running slow because of too many indirections, stacks that are too big etc. We can optimize for direct code readability! Then there are the "why" comments. Those can be invaluable. If I assume I have the kind of good code I can just read as to the "what is this doing", I can sparingly add information to things that might seem unusual or weird or inexplainable. Same with tests mentioned in some sibling posts. Tests should be written in a self documenting way. I like to name my tests after what they're testing. Like "should behave in X manner when doing Y to Z" from a user's point of view, not on a technical level. User not necessarily meaning end user, say if you're testing an API or library function. Different language make this easier or harder but I do it in all of them. Armed with that documentation of what my tests pre-requisites are and what the expected outcome is, I can write the actual test. I should be able to deduce the expectations of the test from the test's "name", thus double checking that I am testing the correct thing. Many tests I find in shared code bases are utterly unreadable, have way too many expectations and side effects and test too many things at once. With the above technique there's usually only one or very few expectations. If I parsed out the test names from all my tests and just gave them to you as a document, it should almost read like a documentation of all of the expected behaviors of my piece of software.

hinkley 4y ago

We have some blatant falsehoods about how documentation should be organized as well. Virtually everyone seems to think that people know which file to open, and so we organize files as if the person is always in the right place. This doesn't scale, because as the size of the project and the number of docs increases, we start refining generic knowledge into more refined slices of the problem domain. At first the docs are so far apart that you rarely miss, but as time goes you miss more and more. So while your outline might suggest that finding docs grows logarithmicly, it's linear at best. The first line of any doc should answer "where am I?" and "why do I care" because the odds that they don't care go up over time, and people put a time limit on self-service. After 2-3 wrong pages in a row they start getting impatient, unless they got through those wrong pages in 5 seconds apiece.

amalcon 4y ago

"Comments go out of date quickly" is true -- it's the "there's no point in investing in them" that's incorrect. In addition to being valuable in the short term (to both you and anyone else who ends up looking at the code), "comment just became outdated" is a highly valuable signal that a prior assumption made by other code could now be false, and you should look into that.

gregmac 4y ago
I have worked on teams where the code is very well documented (basically every public method, parameter, property or class gets a comment) and it's not at all hard to keep up to date. Sometimes people forget, but when you look at a PR and see the usage or meaning has changed with no corresponding comment change, it's easy to flag.

treeman79 4y ago

I used to have an amazing working memory. Could keep a dozen things in mind at once. Or context switch fast enough to be the same effect. Had a series of strokes. Mostly recovered but now short term memory is one thing at time. I have leaned to document like crazy as I’m working. Todo lists are my life now.

zelphirkalt 4y ago

Usually when writing some code, which deals with something new for me, I get many "idiot questions" in my head. I try to write comments in a way, which will answer my future self's "idiot questions". Answering all those questions, I feel more like I truly understand, what I am doing.

arithma 4y ago
I often don't comment code, especially in personal stuff, but when I occasionally do, which happens mostly when things get overwhelming, I find bugs or fix things that I was stuck on. Writing forces you to understand better, name better, and almost feels like providing you with another perspective, all without leaving your own self.

SkyMarshal 4y ago

One way to cap the cognitive load of adding and maintaining comments is to limit them to explain why a piece of code does what it does, rather than how. Rely on the fact that the how is self-documenting to other programmers who may need to maintain your code later (including you), but the why is not always so. Eg, were other options considered and this one chosen? Why? Is this piece of code non-standard or particularly clever? Why? Is this piece of code more complex than it seems like it needs to be? Why? Does this piece of have non-local dependency that may not be obvious at first glance? Are there security concerns with this piece of code which are non-obvious to a novice or an outsourced worker? Etc. There's the old saying, "since debugging code is more difficult than writing it, then if you write the most clever code you are capable of, then you are by definition incapable of debugging it". Pretend you're explaining your code to future you who has forgotten why you did what you did and isn't clever enough to debug it.

fishtoaster 4y ago
I think "why" comments are the most useful, but "what" comments are a bit undervalued. A few types of "what" comments are, I find, very useful: 1. Comments that are effectively headers: # If the user is foobar, do thing user = User.find(current_user_id) user.preload_bizbaz!(cache: false) is_foobar = user.bizbaz.foobar.status == "yes" if (is_foobar) { do_thing(user) } Yes, you can read the 4 lines of code to see the "what' - the comment is duplicative. But when I'm skimming through a large codebase trying to find or understand something, these headers can be invaluable. 2. Comments on dense code # Matches any email like foo@bar.com (only .com, .net, .org email addresses) return email.match(/^.*@.*\.(com|net|org)$/) Yes I can that regex, but I can read that comment a lot faster.
- vikingerik 4y ago
  And the latter is a perfect example of what goes wrong, when someone adds "gov" to the regex but doesn't notice the comment to update it.
  - Arrath 4y ago

branko_d 4y ago

I practice something I could only describe as “comment-driven development”. Whenever I need to implement something non-trivial, something that might have subtle edge cases or has to be done in a certain way because of the external dependencies, I first write the comment before writing the code. I might iterate on the comment, not unlike one might iterate on a design document, and basically use it as a mental tool to fully understand the details of what needs to be done. After I do that, I use the comment to remind me about all these details as I go through the implementation. All this is doubly important when designing an API, where the comment (also) serves as the externally visible documentation for that API. It helps me put myself into the shoes of the caller reading that documentation without knowing the implementation details, which I believe helps me design a better API. I hear that “comments go out of date” a lot, but in my case, if a comment doesn’t match the code, it’s usually the code that needs fixing.

dotancohen 4y ago
I do the same thing. I then replace the comment with a method name that describes exactly what the comment described, e.g. _getLowestFooIdFromBarCollection(). I then implement the code inside this private method.
- rlayton2 4y ago
  Similar to my strategy. Write the code as if I had all these magic functions that did steps: def write_report(): db = connect_to_database() data = get_data(db) summary = summarise_data(data) save_report(summary) After this, do the same for each of these functions.
  - adolph 4y ago
    I do pseudo code sometimes too. I notice that your functions/methods/whatever are verbs that are assigned to nouns. It reminds me of: Verbs in Javaland are responsible for all the work, but as they are held in contempt by all, no Verb is ever permitted to wander about freely. If a Verb is to be seen in public at all, it must be escorted at all times by a Noun. http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-nouns.html http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom...

daotoad 4y ago

We need to write code that is optimized for communication and clarity. We have a number of tools we can use to craft communicative code. 1. Variable and function names. These should be descriptive and never deceptive. For example, I've seen metric tons of code like this `const json = makeSomeApiCall(params)` where the contents of `json` is a the decoded response data and not a JSON string. This code is deceptive and obfuscatory. But if you write `const decodedFooResponse = makeSomeApiCall(params);` then you are accurately describing what the value is. This is particularly import in untyped/loosely typed languages where the value of the variable could be anything. 2. Code structure and layout. When writing prose, we achieve clarity through structure. Code is no different. Keep related things together. Avoid run-ons. In other words, write code that has smallish functions, with smallish interfaces, it's easier to reason about how the code will behave. Avoid unnecessary mutation of values--repeated mutation of the same value is particularly pernicious. Use white space to create visual separations of distinct ideas. Use abstraction and encapsulation to keep code focused. Avoid deeply nested conditionals, flattening the tree whenever possible. And a million other strategies that can all help. 3. Tests. Tests can be documentation, but they certainly aren't always. They also aren't convenient documentation--what they offer isn't going to show up in your editor when you inspect a method. Unit tests are a nice way of recording verifiable expectations for behavior. But if the test code is complicated or poorly organized, all it does is compound the misery of working on a messy codebase. 4. Comments are distinct from documentation here. Comments are little side notes like "this implementation is a bit of a hack. It is brittle because .... but we decided to keep it because X. See someURL for contemporaneous discussion." They tell us why a thing is the way it is or about some sort of risk or unexpected detail. 4. Documentation is absolutely a part of making code understandable. These docs are primarily going to be used in an IDE/editor when viewing function signature data. Ideally you can write JavaDoc/TSDoc/POD or similar inline docs. Examples are worth their weight in gold. We should be using all our tools to write communicative code. We don't need every technique for every line or block, but over the scope of a package or project, we should judiciously employ them all. Every line added comes with a concomitant maintenance cost--we must ensure that every line we add is worth that cost.

jarjoura 4y ago
This should be the top reply! Just want to add my extra take on comments: Comments are absolutely necessary when explaining complex logic that is hard to read for the casual reader (or yourself 6 months later). Comments are not necessary when the code itself explains what it does by being clearly named, isolated and organized. Comments are not documentation and shouldn't be used as such. They are tools to improve code clarity for the person who is changing the code. They are not tools for someone who is using the code. If the intent is to teach someone what the code does so they can use it somewhere else, write documentation in a wiki with examples and link the wiki URL to that point in the code.

suprjami 4y ago

This reminds me of an anecdote about code which was always beautifully commented. The author would code while wasted and couldn't remember anything if it wasn't on the page in front of them, hence the comments.

r24y 4y ago

One thing that I believe is under-documented in code is _business decisions_. The team arrives at a decision in a meeting or informal discussion, and it leads to some code that might be tough to understand without context. I'll usually add a comment briefly describing the decision, and initial and date it. Initially I would just link to a wiki page in a comment, but occasionally these links break, so in my experience it's better to include the notes directly.

Archelaos 4y ago
It is often also useful not only to document the decision the team arrives at, but also briefly write down what was decided not to implement and why. This is very helpful when people come in a few weeks later with a "new" idea that has already been discussed, or in onboarding new people to the project.
tcoff91 4y ago
The commit message should contain all the unusual context needed to understand the change. In practice however, most people write terrible commit messages.
- ParetoOptimal 4y ago
  Many never even use multi-line commit messages.
- bornfreddy 4y ago
  It's not just that. Commit messages have a property that they get overwritten. When I refactor some code for performance reasons, I don't want to remove documentation - which is exactly what happens if I make a commit. True, older commit messages are available in the history, but... not conveniently available.
- conradfr 4y ago
  And ideally the id of the ticket associated to the code change.

stavros 4y ago

I feel like many people take the "comments will go out of date" adage the wrong way. To me, it doesn't say "don't write comments", it says "give your comments some love while you code". It's meant to warn against letting comments become false, not against writing them. To me, at least.

tayo42 4y ago

> You can document your code. You can keep it up to date. It isn't that hard. You just don't want to. Yeah I can or an individual can, that misses the point of the advice which is intended for groups on large projects with deadlines. Like once a manager says get this done now and we'll find time later for the rest... That never happens

bee_rider 4y ago

I have a similar issue. I ended up pretty good at math; had to re-derive everything every time.

justbaker 4y ago

>You can document your code. You can keep it up to date. It isn't that hard. You just don't want to. YES

foerbert 4y ago

Same issue here. It's one of the reasons I've become so enamored with Ada. With Ada, it's not only easy, but encouraged, to encode so much information in about how things are modeled into the program itself. Not only does it function somewhat like documentation, it also lets the compiler helpfully yell at me when I still manage to forget how things actually work. It's saved me so much stress and debugging time. Now if only any of these 'safer' languages would add even just strong typedefs. Even if they don't particularly encourage their use, it'd be something.

baby 4y ago

Oh gosh, this 100 times. I comment everything, even rationale behind decisions, I'm recently writing a book as I write a compiler[1] because some parts are confusing me so much that I just can't solve them, and can't go back to work on them later, if I don't document them. Even if things go out of date, it does not matter, because it still is somewhat close to what used to be there and can still help the future reader (me or someone else) figure out what might have happened since then. It's a million times better than no documentation. [1]: https://mimoo.github.io/noname/ https://mimoo.github.io/noname/

throwawaylinux 4y ago
Changelogs are very good for that if you write good changesets. They don't go out of date either, because you know exactly what source they apply to.
- baby 4y ago
  I feel like nobody goes to look at changelogs, or PRs, or commits. Probably because they don't ever expect anything good from it. Also they're not really searchable.
  - jlokier 4y ago
    It depends on the project. Linux kernel commits often have excellent messages, because that's the standard expected.
    - baby 4y ago
      But still, how would you search through commit history to figure out one thing? Comments are right here in the code, and books/external doc/rfcs refer to concepts. I feel like commits are only good if you're spelunking, which is usually for a single reason: you're bisecting looking for a bug.
      - jlokier 4y ago

dllthomas 4y ago

> You can document your code. You can keep it up to date. It isn't that hard. You just don't want to. Documentation that is close to the things it is talking about isn't hard to keep up to date. What is hard is knowing, when I make a change here, that someone (maybe me) talked about this thing over there without any pointer from here to there. Can I do a careful search of everywhere there might be documentation every time I make a change? Yeah, I guess; it'll definitely slow me down in the short term and I'll still miss things.

andirk 4y ago
Does "documentation" mean separate documents completely disconnected to the codebase? Isn't that the problem? Code gets updated according to necessity whereas documentation is for human consumption and not required to make the thing work.
- dllthomas 4y ago
  > Does "documentation" mean separate documents completely disconnected to the codebase? At worst, yes. I've increasingly seen docs in Notion, but Confluence was common before and probably still is. I agree that a big part of the solution is "get it all in the repo" but I don't think that's enough. Even within a repo, writing can be pretty distant from the code it discusses. In my experience, programmers and reviewers are great about comments on or adjacent to changed lines (not coincidentally, what shows up in git diff and code review software). Both are still pretty good about comments that they can structurally expect to be present, like function documentation at the top of a function. It falls off a lot for programmers when it's a comment talking about something more than maybe 20 lines away, whether that's a quick sketch at the top of a loop or a block comment somewhere in the file about invariants or caveats or gotchas. At that point, reviewers simply will not catch that the programmer didn't update the documentation, unless they happen to be unusually familiar with the file in question. Comments that reference code in other files are thankfully rare if you have reasonable modularity, but will also be missed by both programmer and reviewer unless the task in question touches both files in a relevant way. Documentation in the repository that is not a part of code is hit and miss. Developer setup guides are often brittle to particular system configurations, but usually get some effort every time the new hire trips over something. Runbooks similarly, and less limited to the new hire, and hopefully you look them over proactively on occasion. Large scope architecture documents are doomed; I am more optimistic about something like ADRs which should be relatively narrow and aren't intended to be updated beyond deprecation. Much of this can be helped with tooling, but where it exists its poorly standardized.

ryan-allen 4y ago

I (should better maintain) my little compendium of shell 'one liners' that do all sorts of incredibly useful things, that getting right first time, were hard won. Having that handy you can seem like a god at times to your colleagues when they are trying to solve something. "Oh, did you know you can do this? I'll message it to you." I think my working memory isn't very good, but there is something in there that is very good surely, because how else would I have been able to computers for this long?

softfalcon 4y ago

The added bonus to writing good comments is you’re practicing technical writing directly associated with your code. It’s similar to writing your own flash cards, but by rephrasing the code into a comment you’re visually and linguistically using a form of repetition to stick the code inside your head with a human readable explanation. This can make you a better technical communicator when discussing any code with others. There is a lot more than “I will read this comment in 6 months and it will save my ass” going on when you practice writing good comments. I really like this because in my opinion, half of my job is good communication, another quarter is planning/design, and the final quarter is actually writing code.

keyle 4y ago

In a world where comments are terse; if it takes longer to grok the code than it takes to read a comment, the comment is worthwhile. // this does x do_x() is a bad comment, however... // this does x OMG_WTF_function_call(rocket science maths & bitmask); is a good comment :)

gernb 4y ago

IMO there is some common sense to comments that is often not followed. Example: I work on a project that has a pre-submit script that requires comments for tests. This leads to ridiculousness where I have code like // Test that uploading data with XYZ function works TEST(UploadingDataWithXYZFuncWorks) { ... } Like WTF! The function name says all that needs to be said. There are is no more info needed but I had to appease some over zealous programmer. Meanwhile, in an existing test in the same file I see code like this // Set the dimensions SetDimensions(0, 0, width, height) Again, WTF! Comments are important for explaining why something exists, what its assumptions are, edge cases, etc..., but you can also go overboard with comments and you can make your code more readable by using readable names for functions and variables.

sooyoo 4y ago

> "comments go out of date quickly, so there's no point in investing in them" The key difference is where the described thing lives. A comment describing the next few lines of code or some loop that follows, or similar, won't go out of date since it's easily updated together with what it describes. A comment living in another file, describing loosely some far-reaching but still-evolving aspect will likely be outdated soon, if the thing it describes changes and that comment is out of sight and needs extra effort to be remembered and updated.

Cthulhu_ 4y ago

That said, walls of texts may not get read. I write walls of text, but I'm sure nobody reads them, not even me :D

ducharmdev 4y ago

Can I work with you? Joking aside, documenting as a habit alongside coding is like a superpower. I find that writing can act as validation against my understanding of a problem; if I struggle to write about it, then it's likely that I don't understand the problem as well as I thought.

HeavyStorm 4y ago

YES! That argument is so stupid. Just do the work.