7 ms·

Don't worry, the code is self-documenting. /s Self-documenting code (what I take in practice means "no comments"-culture) is something I don't understand how i

• the-smug-one 4y ago
  The why should be clear from the domain that you're working within. A line of comment should count as something like 10 lines of code, if you're reading a comment then you're treading into real complexity. If you're in a code base where that isn't true, then is the comment really necessary? Fairly hot take from me, life is more ambiguous than that :-).
  • saiya-jin 4y ago
    Unless you are in some trivial startup domain, real domains (TM) have almost fractal-level complexities if you dig deep enough, corner cases, sometimes illogical rules etc. The "why" is still very much needed since it can have 10 different and even conflicting reasons, and putting it in the code in appropriate amount shows certain type of professional maturity and also emotional intelligence/empathy towards rest of the team. I mean, somebody has to be extremely junior to never experience trying to grok somebody's else old non-trivial code in situation when you need to deliver fix/change on it now. And its fairly trivial to write very complex code even in few lines, which some smart inexperienced juniors (even older, but total skill-wise still juniors) produce as some sort of intellectual game out of boredom.
    • eru 4y ago
      And even more important than the 'why' can be the 'why not'? Ie explanations for implementation choices that haven't been taken for various reasons.
    • rob74 4y ago
      > I mean, somebody has to be extremely junior to never experience trying to grok somebody's else old non-trivial code People are definitely capable of looking at someone else's code and saying "this crap is completely unreadable, we should rewrite it all", while at the same time believing that their own code is perfectly readable and self-documenting.
    • kasey_junk 4y ago
      I’m not a “no comments” maximalist but someone has to be pretty junior to have never experienced a comment that is just completely incorrect. It’s really hard to write a good comment that is only “why”. It’s really hard to keep comments up to date as code is moved and refactored. And an incorrect comment is much more damaging than no comment at all. That’s the driving force behind “self documenting” code. My view is that a comment is sometimes necessary but it is almost always a sign that the code is weak.
      • Oddskar 4y ago
        > It’s really hard to keep comments up to date as code is moved and refactored. Hard disagree with this. If your comment is so volatile then that really sounds like there's something architecturally wrong with the code. Most of the time these kind of "comments" can be turned into either a test, or a extensive description that goes into version control. Because commit messages are just that: a comment for a specific moment in time. There are lots of options to inline comments.
        • acka 4y ago
          Which is why I find looking at `git blame` (or one's favorite IDE's/SCM's equivalent) output so very useful in case of undercommented code.
      • saiya-jin 4y ago
        > It’s really hard to keep comments up to date as code is moved and refactored I agree with this, but if the explanation for logic has good reason to be there, then keeping comments up-to-date with code changes is very important and it goes back to seniority and empathy I mentioned earlier - if you understand why its there in the first place, and you actually like rest of your team, you are doing too all of you a big favor with updates of comments. Each of us has different threshold for when some text explanation should be provided, which is source of these discussions. But again back to empathy, not everybody is at your coding level, you can save a lot of new joiner's time (and maybe a production bug or two) if they can quickly understand some complex part.
  • pjmorris 4y ago
    > The why should be clear from the domain that you're working within Sometimes the 'why' is purely domain knowledge. Sometimes the 'why' is about narrowing down options available in the domain. Sometimes the 'why' is about a choice made for reasons that aren't specific to the domain. And sometimes the 'why' is about the code that wasn't written, so it can't possibly be in the code that was.
    • Jenk 4y ago
      "Sometimes" doing all the lifting there. Comments are supplemental. If you have just added some weird, non-obvious, bit of code because you needed to compromise, or work around some other quirk, go ahead and comment. No one is going to (sanely) object to that.
      • pjmorris 4y ago
        What you describe is how I tend to comment. At the opposite end of the spectrum we have Knuth's 'literate programming', exemplified in Tex, which has as its goal 'making programs more robust, more portable, more easily maintained, and arguably more fun' [0] by merging documentation with code. I'd bet if you counted documentation lines vs. code lines in Tex they'd be near 50/50, and I'd bet that if we asked Knuth whether the comment lines were supplemental he'd say no. [0] https://www-cs-faculty.stanford.edu/~knuth/lp.html https://www-cs-faculty.stanford.edu/~knuth/lp.html
    • kwhitefoot 4y ago
      > sometimes the 'why' is about the code that wasn't written, so it can't possibly be in the code that was. I have often had to write extensive comments related to this to prevent well meaning coders who are not expert in the domain from replacing the apparently bad or low performance code with an obvious but wrong 'improvement'.
      • P5fRxh5kUvp2th 4y ago
        In a perfect world, tests and assertions would protect from that, but yes, that's a good use of comments.
  • simion314 4y ago
    The developers , especially new ones do not understand or know all the history of the project. I remember one time in css I had to do something weird like min-widht:0; It was needed to force the css engine to apply some other rule correctly,. but this will puzzle you when you read it. And this kind of puzzling code needs comments, I prefer to just put the ticket ID there and the ticket should contain the details on what the weird bug was with all the details, so if some clever dev wants to remove the weird code he can understand stuff. Sometimes I see in our old project code like if webkit to X else do Y , there is no comment with a bug link so I have no idea if this code is still needed or not (Browsers still differ in more complex stuff, like contenteditable )
  • auggierose 4y ago
    Code is almost never self-documenting. That's why there are so many O'Reilly books out there. A great example is AWK: It's a tool, and it comes with a book from the people who made the software. That's how I like my software.
    • pjmorris 4y ago
      To your point, we also have 'The C Programming Language', K&R, and 'The Unix Programming Environment', K&Pike.
      • auggierose 4y ago
        Seems like the common denominator is the K here!
    • vjust 4y ago
      Or the Emacs book.
  • yourapostasy 4y ago
    > The why should be clear from the domain that you're working within. I hear this commonly from coders who haven't had the ambiguous pleasure of working with old, production critical codebases from generations of coders who have come and gone, with technical decisions buffeted around by ever-shifting organizational political and budgeting winds. Knowing the why's that leadership cares about is far more important to your career than the technical why's, which are along for the ride. Once you go into production with tens of thousands of users and up, with SLA's driven by how many commas of money going up in smoke per minute...yeah, illusions of "pure" domain knowledge driving understanding of function dictating code form evaporate like a drop of distilled water on the Death Valley desert hardpan in the middle of summer. I used to be like that as well years ago, but some kind greybeards who took me under their wings slapped that out of me. Now my personal hobby code with an "unlimited" budget and I'm the sole producer and consumer? Yep, far closer to this Platonic ideal where comments are terse and sparse, and the code is tightly coupled to the domain.
  • P5fRxh5kUvp2th 4y ago
    I don't like such rules of thumb. A better approach would be that A comment should tell you something that you cannot glean from the code and/or is non-obvious. Yes, I understand non-obvious can have a truck driven through it, but in general it should work. You can read code and understand what it's doing mechanically, but you may not understand why the obvious approach wasn't taken or understand what it's trying to achieve in the larger context. Feel free to comment on those, but if the code is difficult to understand mechanically, the code is generally bad. Not always, everything has exceptions, but generally that's true.
• ilyt 4y ago
  I like that term. When I hear it I can with 100% accuracy know the person touting it is a hack and their code is garbage.
• jalapenos 4y ago
  In practice it really does mean self documenting code. Like variables called "daysSinceDocumentLastUpdated" instead of "days". The why comes from reading a sequence of such well described symbols, laid out in a easy to follow way. It doesn't do away with comments, but it reduces them to strange situations, which in turn provides refactoring targets. Tbh, its major benefit is the fact that comments get stale or don't get updated, because they aren't held in line by test suites and compilers. Most comments I come across in legacy code simply don't mean anything to me or any coworkers, and often cause more confusion. So they just get deleted anyway.
  • jjgreen 4y ago
    Better, a "last_updated" method on instances of "Document", that being an "Age" instance with a "days" method: document.last_updated.days Self describing code does not need theRidiculouslyLongNamesPerferredByJavaCoders.
    • jalapenos 4y ago
      Yes, was just an illustrative example
  • Oddskar 4y ago
    In most cases, even though there's verbose variable names you still can't understand the why just by reading the code. And even if you did, why would one want to? Most often I'm just skimming through, and actual descriptions are much better than having to read the code itself. This whole notion of "documentation can get out of sync with the code, so it's better not to write it at all" is so nonsensical. Why isn't the solution simply: "lets update the docs when we update the code". Is this so unfathomably hard to do?
    • greenmana 4y ago
      People are lazy.
      • 4y ago
• croes 4y ago
  I've seen lots of documentation that I only understood after I understood the code.
  • Oddskar 4y ago
    In other words: poor documentation.
• ethbr0 4y ago
  The dream of self-documenting code requires solving two problems, only one of which programmers are typically good at. 1) Communicating with computers 2) Communicating with other humans Self-documenting code is essentially writing prose. Granted, to someone with similar knowledge as you. But most people suck at writing.
  • Ma8ee 4y ago
    I have better hope that a good programmer can write readable code, than that they will write readable documentation. As you point out, people suck at writing.
• cafard 4y ago
  I would remark here that The Mythical Man-Month did give a page or two to documentation. My copy seems to be out on loan, but as I recall the section included a figure showing the documentation for a sort function, perhaps 25 lines or so.
  • InitialLastName 4y ago
    > My copy seems to be out on loan, Drifting off-topic, but I wonder how close to the top of the list TMMM is for "on loan" duty cycle in the software world. My copy also seems to be persistently in someone else's hands.
  • Ma8ee 4y ago
    If I remember correctly, Brooks experience was with assembler, which might require some more documentation than modern Java or Python.
    • cafard 4y ago
      I think that the example was in PL/1.
• lightbendover 4y ago
  Documentation without accurate and descriptive method/member names is much more harmful than the inverse. If an abstraction is sufficiently complex to warrant a lengthy description of why it exists, then it should have a design doc. In practice, most code within a repo is pretty simple in what it accomplishes and if it's confusing to a reader, then it is most likely because they don't understand the design of the larger component or system or simply because the implementation is poor. There are of course cases where comments are really useful or even necessary (e.g. if going against best practices for a good reason or introducing an optimization that is for all intents and purposes unreadable without explanation), but they are exceptions.
• Kranar 4y ago
  At my company code is required to be self-documenting. My attitude is that if you can't determine the why then you likely are not familiar enough with the problem domain to be working with that code. It's fine not to be familiar with the domain and there are ways to address that, but reading source code is not one of them.
  • ambicapter 4y ago
    So you bar all junior developers from writing code until they've gone through tested coursework in your domain, or what?
    • Kranar 4y ago
      Yes absolutely. All developers, junior and senior, go through a 4 month training program working on a completely independent project from scratch that teaches them everything they need to work in their domain. There are exceptions now and then, but for the most part it's pretty consistent. When a developer wants to switch from one area to another, they go through an accelerated program (takes only about a month).