17 ms·
The Documentation Triangle, or, why code isn't self documenting
- jpswade 4y agoCode should explain the what, tests should explain the why. Done correctly comments should be redundant. That doesn’t mean actual documentation isn’t useful, but it only captures a point in time, rather than the actual living code.
- pharmakom 4y agoCode could be self documenting if it had constructs for everything we might want to say, but I don’t think that would be a practical language.
- Jistern 4y ago
- Brajeshwar 4y agoThe article is more of a reasoning than a question of why. I find it worthwhile to read and help me clarify when answering questions to junior developers on why they should focus on writing helpful documentation.
- Jistern 4y agoWhy not tell them, "Newton and Einstein wrote documentation. How do you think we learned from them? Oh, and by the way, we fire developers quickly around here who don't document their code properly."
- adam_arthur 4y agoWish the article went into a bit more detail on the thought process. Code absolutely can be written in a self documenting way, just that most people don't structure their code like English/natural language. Also some languages have too much syntax bloat to be written effectively in a self documenting way. I agree with the principle that some things are better expressed through documentation, such as motivations and higher level diagramming. But the average code base is so far from being self documenting, that the gap there should be closed first before moving on to external documentation. External documentation creates a second source of truth that often falls out of sync with the code, so becomes a form of technical debt/maintenance burden. The best way would be exporting docs from your codebase, and have all documentation related artifacts expressed alongside the code. Diagrams expressed in a programmatic DSL etc
- throwawaylala1 4y ago> The best way would be exporting docs from your codebase, and have all documentation related artifacts expressed alongside the code I LOVE Golang's approach to this [1]: - Documentation generation from code is built in to the language toolkit - There is a standard for writing the comments so all of them look the same across every project - It even supports code examples which are visible as a REPL in the generated docs When people ask "what's so great about Go?". It's stuff like that which is hard to succinctly describe but makes a huge difference in overall quality of Go code in the wild. [1]: https://go.dev/doc/comment https://go.dev/doc/comment
- pjmlp 4y agoSo basically what Common Lisp, Smalltalk, Java, Perl, Python and Ruby have provided before Go was a thing. Many of the Go features are only a win when the competition is C.
- doctor_eval 4y agoI can’t speak for the others, but Godoc is IME way better than JavaDoc, which is both hard to write, and hard to read inline due to all the f*ing HTML. More to the point, just because some platforms provide equivalent functionality doesn’t make the GP wrong.
- euroderf 4y agoA nice Javadoc touch that Golang could use is to break out the documentation of arguments and return values.
- throwawaylala1 4y agoSo here's an example of the string package: https://pkg.go.dev/strings https://pkg.go.dev/strings In what way would the JavaDoc @param/@return/etc annotations actually help? What Godoc has is more than suitable for the vast majority of cases.
- galkk 4y agoAs someone who recently started working on a project, that requires a lot of domain knowledge (database internals), I can definitely say that the code may be perfectly readable (variable names, patterns, even comments), but still not self documenting, because you need to have so much context, crammed in your head.
- stellalo 4y agoI would have thought that “what = context” and “how = code”
- abathur 4y agoI think there's a perspective slip here. I assume it means: What does the code do, why does it do that, and how do we leverage it. These perspective issues are tricky. There's a difference between "what does the code do" (low level) and "what does the program/command/API do" (high level). There's a difference between why we need the code to do x, and why the code does x in one way and not another.
- mihaigalos 4y agoI see tests as documentation. They show you how to interact with a component and what the expected behavior should be. In BDD, you go one step further and write down a formal description of inputs and expected outputs. Would agree that the higher level documentation (diagrams, process interaction, etc.) can be written down once the dust settles.
- rmnclmnt 4y agoTotally agree: tests are the living documentation of usage! And if the team is properly collaborating, they are linking issues and merge requests with commits, providing historical snapshots of the ever evolving context!
- AlotOfReading 4y agoI find tests to be terrible usage documentation. Better than nothing to be sure, but compare compiler tests to a tutorial or example code for learning a programming language. The former are usable, but often full of obscure edge cases, layers of abstract test infrastructure, and mocks. The same probably applies to the tests in your codebase as well. They're just not designed for pedagogy in the same way docs should be.
- rmnclmnt 4y agoIf your talking about learning and pedagogy, that's an entire different subject. When you are working on obscure code, you are not learning how the programming language works at the same time (I hope not). If you do, split the problem in two: learn on one side and apply on the other one. And yes tests are not the best candidate to learn how to do stuff. The best candidates for this are out of band documents / media / training.
- AlotOfReading 4y agoThe language thing was simply an example of an interface where it's very clear what the difference between proper documentation and tests is. It's the same sort of problem, but a slightly different context.
- travisgriggs 4y agoThe problem I wrestle with is “comments lie.” Not all the time of course, but often enough that I often end up reading the code to make sure anyway. It’s those very “why?” and “how?” comments I’ve seen lie. My own have lied to me. As have my teammates. They go in at one point, the code evolves, the comments become misaligned. I’m not trying to justify no comments. I just wish there were a better solution to this very real issue.
- rich_sasha 4y agoI have experienced it, and never have I found it anywhere near as bad as no comments and "self documenting code". IME it's mildly obvious when the comments are obsolete or out of whack. It's testing one hypothesis. Whereas with no comments, there are basically an infinite number of possible hypotheses as to what the code does.
- skohan 4y agoI think the best solution is having a few tactical comments. Imo the best setup for a project is: 1. Some high-level documentation explaining how the key systems work and interact conceptually, to give context. 2. Comments for anything non-standard (i.e. we're using some weird encoding here instead of JSON because of XYZ reason) 3. Comments for the tricky extra complicated bits For everything else, well-written code following standard conventions and good naming practices is enough. Also choose a statically typed language, so that your function signatures will give you a useful contract to work with, and it will mostly be pretty easy to trace the intent of your code.
- chriswarbo 4y ago> Also choose a statically typed language, so that your function signatures will give you a useful contract to work with, and it will mostly be pretty easy to trace the intent of your code. Furthering this, avoid: - "Stringly typed programming": where everything has a static type, but they're all `String` (or `Int`, `Float`, etc. instead of something with domain meaning). This gives very little information to the reader, and makes it easy to mix-up values. - "Boolean blindness": where we query a bunch of booleans to determine what data we can extract, e.g. Result::hasUserId : Boolean Whether this result contains a UserId Result::getUserId : UserId Returns a UserID if hasUserId; otherwise error log("Request came from " + myResult.hasUserId? myResult.getUserId : "anonymous guest") Compare this to e.g. Result::getUserId : Option[UserId] log("Request came from " + myResult.getUserId.orElse("anonymous guest"))
- dmitriid 4y agoWe have an Excel report generating code at work. It's extremely straightforward to read... once you understand the requirements and limitations, and some intricacies of Excel format. So there's a 5-page accompanying document that explains those. Code is very, very rarely self-documenting on its own. Because more often than not you need to know most of the code, most of the context and history of the code, and the business domain this code is intended for to understand it.
- abathur 4y agoNo silver bullet. It helps to write thoughtful comments. It helps to pick thoughtful names. It helps to weave a story out of the names you've chosen. I have been picking at some thoughts on the ~naming side of this recently... https://t-ravis.com/post/doc/what_functions_and_why_functions/ https://t-ravis.com/post/doc/what_functions_and_why_function...
- urthor 4y ago1. "Comments are bad" is bullshit. Definitely put the comments in the docsting or equivalent for your language, not in the middle of the function. The best place for comments is nicely grouped under (or above, an elegant C++ convention) the interface. If the function signature is 200 LOC away... the problem isn't the comments. But they should be there. 2. People, need, diagrams. People NEED a picture. At the minimum, the bare minimum, your application needs a high level and low level diagram explaining how it works.
- wryun 4y agoI do not usually use diagrams. Therefore... I'm not a person? :)
- urthor 4y agoHave pity on us mortals. It your first week onboarding significantly easier in my experience, the first time I encounter a codebase. I'm sure people make do without. Lotta science behind it, humans work much better if there's a diagram with coloured shapes/lines involved.
- scrapheap 4y agoDiagrams have their place, and a high level diagram can be very useful, but I find that low level diagrams usually tend to be a lot more trouble than their worth. They get complex and both hard to understand and maintain, which means they tend to get ignored when changes happen and become out of date. I've found that if I'm struggling to create a diagram for something in Mermaid then I've gone too deep in my explanations and it's time to step back.
- urthor 4y agoMaybe I need a better way to phrase it. High level architecture diagrams, user journey diagrams, low level diagrams, are probably all distinct topics. I feel all three are extremely important, but that's bordering on my opinion. > but I find that low level diagrams usually tend to be a lot more trouble than their worth Out of date low level diagrams are surprisingly useful. One of the things that I've found is that, with extremely high LOC projects (LOC definitely measures complexity), you'll find that low level diagrams are worthwhile, at the cost of a time investment in generating them. When/how to do them is a certainly a fine art. There's no right answer.
- jbay808 4y agoHere's an example of a very useful comment: # using heapsort instead of quicksort # because we care about the worst case heapsort(data) Code alone cannot tell the reader why heapsort is chosen, nor whether that's how the code should be. And tests are unlikely to capture this either.
- vinay_ys 4y agoWhile it is useful to have a short comment like this in the code as a quick reminder, such design choices belong in a more detailed technical design document which explores multiple design options and provides rationale for making the final choice. Usually, there will be a trove of useful stuff in code review comments etc that should find its way into such a technical design document. To ensure it gets done alongside code, I prefer wiki docs that sit alongside code and doc changes can be part of the same code commit as well.
- xmprt 4y agoIf comments can lie then design documents can lie even more. There are three tiers of documentation in my mind. Code, comments, and documents. Code can't lie (although it can be misleading with improper naming or bad abstractions). Comments can be completely false (although they're easier to catch because the comments sit alongside the code) Design docs almost always lies and it's hard to catch the lies because a design doc written 2 months ago is never going to match the resulting code perfectly. In my experience, people rarely update documentation unless there's a dedicated employee/developer advocate who is helping enforce and drive the culture.
- trashtester 4y ago> a design doc written 2 months ago is never going to match the resulting code perfectly. That depends how you're writing design docs. If a design doc contains arbitrary flowchars about what happens in the code, it will change. But if you come up with designs similar to design patterns, you can document the pattern once, and use it in your code the way you use a design pattern. Concepts that span a large codebase is also enormously paintful to figure out from reading the code. For instance object models / microservice architectures, complex state machines or security frameworks are hard to catch implicitly from reading the code.
- remoquete 4y agoLooks like that the answer for most is tools, or some new code convention. While that can be useful, the solution to facilitating code comprehension can only be documentation. And to create documentation, the key component are not tools; people are. Technical writers, editors, and others.
- wryun 4y agoWhat often frustrates me is that a lot of doco isn't read: it's "easier" for people to ask (I don't exclude myself from this).
- euroderf 4y agoThe triangle has What, Why, How. But don't forget Who & When. Make sure the footer has a last-modified and a contact/feedback email address. Maybe Where is not so important tho.
- js8 4y agoWhere is important too. I like if I can look at the codebase and see where the (particular) action is. There is too much ravioli code that hides this behind interfaces and factories. As an aside, I think the article has what & how swapped. The code tells you how, but not what (is the correct thing to do).
- euroderf 4y agoI meant Where geographically. But yes, Where in the maze of twisty winding function calls and class hierarchies and delicious concurrent ravioli threading architectures.
- elevaet 4y agoIsn't that what the commit history is for?
- sidlls 4y agoEven api docstring comments are generally terrible. They aren’t sufficient and the infatuation with automatic documentation in our industry is terrible.
- galaxyLogic 4y agoAfter years of struggling with the question of how to write "good comments" I've come up with a solution I'm currently happy with. The main problem with comments is they make code less readable because they interrupt the flow of code-reading and thus code-understanding. But now, I write all my multiline comments in this style: /*------------------------------------------------- This is a comment */ In the IDE I am using (WebStorm) there are keyboard shortcuts for collapsing and expanding sections of code. For comment-sections like above it collapses them into: /*--------------------------------------------- ... */ What this does is it turns a code-reading distraction (the original multi-line comment) into .. a SINGLE LINE SEPARATOR. Single-line separators do not negatively disrupt the flow of reading the code. In fact they actually help code-reading by dividing the program into semantically coherent code-sections separated by what looks like a simple horizontal line. I'm no longer very concerned about out-of-date comments, I accept them as fact of life. They are ok as long as they don't impact my code-reading negatively. I don't need to ponder: Is this comment too long? It is not when it is collapsed. And comments will still contain much useful information. If I don't understand why some section of code is there or is written the way it is, I can expand the comments around it and maybe I find some helpful information there. Often I do. I do wish the IDE would offer more support for this style of commenting. It would be great if all multi-line comments would be collapsed by default. I haven't figured out if that is possible in my IDE. I do know how to "collapse all sections" which is what I frequently do. It is a good way to start reading a code-file anyway. So, the trick is really simple: Start every multi-line comment with a line that consists of a line of dashes.
- JaceLightning 4y agoOften times I read the code instead of the documentation. Why? It's faster, but more importantly the documentation says what should happen. The code says what does.
- IIAOPSW 4y agoimport random comments = [' ',' ',' #this is a loop',' #is this tehcnically a quine?',' #small optimization'] code = ['import random','comments = ','code = ','code[2] = code[2] + str(code)','code[1] = code[1] + str(comments)','for i in code: print(i + random.choice(comments))'] code[2] = code[2] + str(code) code[1] = code[1] + str(comments) for i in code: print(i + random.choice(comments))
- ktpsns 4y agoIt is a quine if we neglect the comments. Interestingly, two of the comments are descriptive (answering "What"). The one asking whether this is a quine is in fact a type of communication widespread in code, when authors use comments for communication.
- IIAOPSW 4y ago>It is a quine if we neglect the comments. Sure. Obviously. But if we don't neglect the comments, is it technically a quine? If one program is different from another in a way that no one can discern by looking at the output or runtime, is it actually different? Are comments part of the code per se? Does "don't interpret this text as commands" count as a command?
- SleepyMyroslav 4y agoThere are types of software where rushing product is the norm. Everyone read stories of long death marches of computer games. These games have millions of lines of code. I would put my 2c that code in these projects is part of the people who made it. You should not expect to be able to understand code without talking to people. Yes patchwork can be intricate and some things may be lost in countless requirement U-turns. What I think was common in successful projects is that people kept some understanding of the code. They might have no incentives to share it with you ^_^. ymmv ofc.
- js8 4y agoI blame the OOP culture for the idea that code is self-documenting (and also for the sibling idea that unit tests can replace documentation). See, OOP worldview is a priori based on the idea that all programs can be written as collections of small, independently reusable, objects. In that world, there is no place to put any high-level explanation of how the parts interact as a whole, or what are any emergent properties of the system, because it is (on the ideological assumption of object independence) not needed. It's very visible from e.g. Java package system design, there is no place to document what a particular package is for, or what classes are part of its public API and what are internal. And in Java in general, every entity must be assigned to some object, the things that lie outside (and can be shared) are frowned upon.
- koreth1 4y agoIt seems like some of these issues with Java are out of date. Java has had a well-defined place for package-level documentation for close to 20 years, since 1.5. It goes in package-info.java (docs: https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#packagecomment https://docs.oracle.com/javase/6/docs/technotes/tools/solari...). As for documenting which classes are part of the public API, you've been able to make classes package-private since Java's initial release. The module system introduced in Java 9 in 2017 takes that further; you can explicitly control which classes are exported to consumers. "Everything must be an object" is still more or less as true as it ever was, though.
- js8 4y agoThanks, wasn't aware of package-info. Yes, the module system is an improvement. Java is becoming more pragmatic as the ideological dominance of OOP is dying out.
- boberoni 4y agoThe article discusses the structure of documentation as three pillars: the what, the why, and the how. I prefer to think about documentation in terms of four audiences: - the student (tutorials) - the chef (how-to guides) - the theorist (explanations) - the technician (API references) Divio [1] has an excellent set of articles that explains this approach to documentation. [1] https://documentation.divio.com/ https://documentation.divio.com/
- rsolva 4y agoThe same excellent documentation framework is also available on this company-independent website: diataxis.fr
- alipitch 4y agoThanks! Also checked the github site. https://github.com/evildmp/diataxis-documentation-framework https://github.com/evildmp/diataxis-documentation-framework
- catchclose8919 4y ago...this is questionable advice that goes against the interest of programmers having stuff to do - we're not segmented into audiences. We want multi-level docs combined/spliced/interwoven together so we can get our work done without wasting gandalfing the docs. > While redesigning the Cloudflare developer docs ...oh, so this is the reason for CF's docs totally uncomprehensible and confusing mess. They've made getting to anythin so comfusing that AWS seems a breath of fresh air in comparison. I dunno, maybe other peoples' brains are wired totally different than mine, but boy, these new fever of "writing better docs" seems to produce the exact opposite effects whenever applied. The few enojoyable docs nowadays seem to be written by old-school unixy geeks and/or people that are not programmers or worse, "documentation developers": physicists, mathematicians, biologists, quants, data analysts etc. seem to do a nice job when they have the time.
- drothlis 4y agoJust watched Daniele's talk. Brilliant, practical advice. Thanks so so much for the link.
- thundergolfer 4y agoOral Tradition in Software Engineering[1] by Bryan Cantrill really helped me appreciate that long comments in code can be a treasured part of a software space. I started my career in a pretty low-comment Ruby codebase, but now count myself as a person partial to adding lengthy 'why not how' commentary in programs. 1. https://www.youtube.com/watch?v=4PaWFYm0kEw https://www.youtube.com/watch?v=4PaWFYm0kEw
- pcr910303 4y agoDocumenting the ‘how’ part, i.e. the documenting the assumptions that the author had on the context this code runs is important; you guess just enough by grepping calls to the function in the codebase, add add some code that works now… and then the original author or another person adds a call that breaks the assumptions you made, and breaking everything… subtly.
- izietto 4y ago> Why (comments) That's what we do in my current company, but I vastly preferred what we used to do in my previous company, which was: > Why (commit description) which prevents comments obsolescence and code dirt
- pydry 4y agoIME commit descriptions almost never get read by anyone.
- izietto 4y agoIm my previous company we used to write them and used to read them, and used to get frustrated when some old commit didn't have enough description. In this company noone cares and we even have squash & merge mode with description truncation, but methods comments can be longer than methods themselves. It's a question of team mindset I guess
- sethammons 4y agoAnd the latest commit is "shifted all indentation per linter" by someone who didn't write the code. Viewing the history of a file is vastly more a pain in the ass to a useful "why" comment.
- izietto 4y ago> And the latest commit is "shifted all indentation per linter" by someone who didn't write the code IME it's not like that at all, commits like "shifted all indentation per linter" are not so common. It's also easy to skip them. > Useful "Why" comments "Why" comments are not so useful to me, I guess that is the point. The add noise in the code that can be moved elsewhere. Consider that I'm not talking about specific implementation choices comments, like # using heapsort instead of quicksort # because we care about the worst case heapsort(data) which is perfectly fine to be in the code, I'm talking about "why" details that may be not present in the Jira/Whatever issue because they are related to e.g. why a bug raised up from a technical point of view.
- usrbinbash 4y agoI'm using "What", "Why" and "How" here as defined in the article. Problem with documenting in the code itself: The "Why" is further from the code than the "What", and the "How" is further away still. Explaining "What" a function does is close to the code, I just put some comment lines before the function/type, etc. and maybe some into the definition. They are just to make the code better readable for the human. But where do I put the "Why"? I could put it with the "What", but often the "Why" depends on somewhere completely different in my code (or someone elses code). eg. "Why am I using a map here instead of a list? Because the remote API expexts a JSON object and the map is easier to Marshal into that". But what if the remote API changes? Okay, I change the code that deals with it, and update the comments for that code. Do I also change the comments everywhere else where this map is used? For that matter, is it explained anywhere else in the code why that is a map instead of a list? The "What" says "this code iterates through the maps values and appends an underscore to each", but is the "Why", which explains why that is a map there as well? In every function that works on that map? My point is, not only is it difficult to explain everything in the code, it's also very very difficult to keep this documentation up to date, because the relationship between a comments location, and the code it belongs to, becomes more complicated the further up we go from the "What".
- catchclose8919 4y agoArticle is confusing and gives zero actionable advice + a fancy "triangle". In general, after you get to a piece of code you need to have thre questions answered: - what problem does this solve? - this is actually the problem how-to guides solve, in practice your particular use case is NOT even close to the example use cases, so you'd just read the how-to guides as the no-bs higher level explanations because you know anything higher level is often bs - how do I get something done with this? - API docs combined with dense explanations combined with dense usage docs (I don't want to have to piece them together myself through my own effort, I want them all in one place) - what is the reasoning for it being implemented/architected/etc. this way? - design docs + "philosophy" section of docs + architecture diagrams
- Wowfunhappy 4y agoI think the author's point is that code by itself inherently can't fulfill all three sides of the triangle. The cleanest code in the world might make it immediately obvious what a program is doing, but not why it's doing it, or the context in which it's doing it.
- JoeAltmaier 4y agoOf course documentation, even when present, even in the code, is often of the "This does X" sort. When you want "You need this to accomplish {larger task}". It's like walking through the forest and wondering where you are, but every tree has a sign on it that says "tree".
- dingosity 4y agoHmm. I mostly agree with the author's statements like "documentation exists so that code can be easily used" and "it [the code] is the most honest account of what actually happens when you run the code." But introducing the triangle as a metaphor infers each member of the triangle is the same type of thing. The "WHAT" vertex is the code itself while the "HOW" and "WHY" verticies are natural language text. "HOW" and "WHY" are not easy to distinguish and seem to be used to mean "context outside the immediate function" and "programmer's intent." I think the triangle metaphor muddies the water a bit. But... I agree with most everything else the author says. Context is important and is not present in the code (usually.) The developer's intent is generally absent from the code and should be supplied somehow. I might even go further to explicitly mention documentation at the top of a function traditionally describes that function's context in the greater scope of the application or module or class while documentation inside the code body often describes the programmer's intention with respect to the function's implementation. (This is just an observation from code I think is well documented. Maybe there are counter-examples out there.) I have a bit of an architectural bent, so I might have talked about documentation and it's relation to interface/implementation and problem domain and solution domain. Which is to say, documentation should be clear about which domain you're documenting. Though I don't understand why the triangle is important, props to the original author for saying "no. code is not self documenting."
- tbwriting 4y ago> No program exists in a vacuum. There is always some environment, some organisation, some process that it lives in or serves, and taken out of said context, it is entirely useless. > Failing to recognise this is the number one leading cause of new users and junior devs being unable to do 'this simple task' (don't quote me on this, I have no data). This. At all three startups I've worked at, founding/senior devs err on the side of assuming that any process not involving writing code is trivial and self-explanatory when in fact those things are some of the biggest time-eaters. Big organizational wins can be had by documenting them well.