https://twitter.com/ChristianSelig/status/1451193663657164810 This thread is fun and has a lot of examples of cool embedded documentation and fancy comment diagrams. It also has a lot of examples of teams, leads and engineering managers removing embedded documentation because it doesn't fit standardized process. I know the "official" FoC stance is to not care much about standard practice (hence the focus on hobby projects, non-programmers or "less serious" domains like education and games), but this demonstrates pretty clearly how common it is for people to have good ideas and useful tools that work for them, only to have corporate process\machine cull them.

wow this epic

I’ve made a few comments like this in readme’s and in code comments before. I am a big fan of long comments in codebases about why something exists or ways in which it could be improved. Big fan of explanatory commit messages, providing context around the history of things, and the avenues tried and discarded. I used to not feel this way. But I’m really not sure now that I understand why. I would have probably said things like comments can be incorrect and/or misleading. But I guess I actually find that fact useful, rather than harmful. If the author thought their code did one thing and it actually did another, knowing that is good for me. Or if the code has changed its purpose overtime, I can discover that via that comment. As I’ve had to fix more and more code, learning the history and purpose of the code is incredibly useful. Having to infer that san-comments is much harder. (It goes without saying that I don’t mean comments like “set x to 2”) I am emphatically anti-external documentation. I think that is the single greatest way to make the documentation 1) not written 2) not read and 3) not helpful. External documentation means I have to know that I need to know something. When I’m reading code, why would I expect there to be something in a totally separate context telling me about this code? (Linking is not and answer. I can’t how many times I’ve read “Please see CEH1282 for more explanation” just to find just to find out that CEH was the project management tool that the company got rid of 6 years ago.) If you want to make these sorts of diagrams and are on the mac, definitely recommend https://monodraw.helftone.com/

Is "internal" vs. "external" the best way to discuss documentation? Elsewhere in this community, people like to criticize that we store code in text files. Isn't that the more fundamental issue? That files( and the tools that process them) guide how we structure code and documentation? I think that the ideas from literate programming (and later computational notebooks) are more useful, even though the tools and techniques from this space are far from mature yet.

In the beforetimes, comments like this were more common. There's even an emacs mode for drawing them: http://www.lysator.liu.se/~tab/artist/

Internal vs external seems a decent distinction to me. The whole point of comments is they are unavoidably attached to a particular piece of code. Clearly external documentation is lacking something, as it always existed and yet people developed this practice of annotating the code in-place.

For me the more fundamental distinction is documentation that guides to the code vs. documentation that answers questions raised by the code. The latter is what I would expect to find "close" to the code, e.g. in the form of comments. Guiding documentation can easily refer to many places in the code, so you can't really put it inside the same file.

I am emphatically anti-external documentation. I think that is the single greatest way to make the documentation 1) not written 2) not read and 3) not helpful. External documentation means I have to know that I need to know something. When I’m reading code, why would I expect there to be something in a totally separate context telling me about this code?

External documentation as done by most companies is often useless because it goes out of date even faster than comments. Ultimately if you want to do this right you have to have a documentation team, make documentation review part of code review, etc. Otherwise, in practice you're relying on arbitrary rules decided by coders in code review, or the converse, which is comment happy programmers that write too much. This doesn't mean external documentation has no value in the same way that saying comments are often useless doesn't mean comments have no value. This is somewhat equivalent to thinking automated testing will solve all quality issues and QA isn't necessary. Not all teams\companies can afford this of course, but it is the most reliable way to ensure quality if you need it. One thing is that many IDEs that programmers use day to day are lacking in documentation capability, which requires "cute" solutions like ascii diagrams above. Google docs is a significantly more powerful documentation editor than any IDE I know of out of the box. Generating more readable\searchable documentation from comment docstrings in code is pretty standard, so that approach arguably gives you the best of both worlds, but if you want to embed images\video, do more complex formatting, etc. most code editors are lacking.

@Scott Anderson: I think there's something here to be understood still with regard to the documentation experience. Having an integrated docs experience can be hugely powerful. For example, editors can be configured to look up documentation directly, as easily as your typical go-to-definition IDE experience (vim has this by default actually, and various language plugins provide the configuration to look up the docs in the appropriate location - the default is just opening up the

man

page for the token the cursor is currently on.) It feels to me that it's going to be extremely difficult to provide enough context in comments for some things (a standard linux utility is a great example of this, where I may want to pull up the man page to review the various flags and their behavior, which is far too much for comment)

that comment above was a quote from @Jimmy Miller that I just responded to btw, I accidently sent it without my response 🙂

I have come up with two solutions to the problem of where a comment should go: • The dramatic solution is to use my approach to Literate Programming: http://akkartik.name/post/wart-layers. It basically looks like a cleaned up git history. When you create a new feature, all the code and tests for it is in a single file, the uppermost "layer". CI guarantees that all combinations of layers work properly: layer 1, 1+2, 1+2+3, etc. And the top of this layer is an ideal Schelling Point (https://en.wikipedia.org/wiki/Focal_point_(game_theory)) for big-picture documentation about the feature as a whole. • The less dramatic solution: Ctags has a way to define cross-links based on regular expressions. If you have a comment that you want to have in two places, just drop it in one place and link to it from the other. Hacky but quite convenient.

@Konrad Hinsen I’m not sure how text documents vs images relates here. To me, internal is inside the system. External is outside the system. Of course, we could debate where to draw the bounds, you could try to claim confluence is part of the system, but that seems a bit of a reach. So internal documentation in an image based system would be documentation in the image. External would be outside the image. I would still keep my same stance there. In text file based systems with git, I consider git part of that system. Then there is the question of “inline” documentation vs non-inline. That of course is a distinction based on the interface we use. In an image based format, that can be configurable in a way text tools don’t traditionally expose. @Scott Anderson

Ultimately if you want to do this right you have to have a documentation team, make documentation review part of code review etc. Otherwise in practice you are relying on arbitrary rules decided by coders in code review, or the converse which is comment happy programmers that write too much.

Yeah, I’m not at all a fan of formalizing these processes. So your otherwise, rephrased, is exactly what I’d advocate for. Let each programmer decide how they want to comment things. Let peer social processes (not power relations) influence and change how that works over time. Uniformity in programming is vastly over-rated, in my view. If you have a comment happy programmer writing too much, talk them about it. I mostly find the opposite, code that makes no sense because of lack of comments. By makes no sense, I of course don’t mean I don’t know what the code in fact does. That is independent of the code. I instead don’t know why the code is doing what it is doing, or if what it is doing is what the programmer in fact wanted. If that person is no longer at the company, my job is now historical reconstruction. There may in fact be a good reason for the strange behavior the code has. External documentation doesn’t help here, or if it does it requires a lot more effort, because it is disconnected from the timeline of the system. Often times the key to why X works in way a1, is because Y worked in way b1 at time t-1 but no longer works that way. This is what external documentation fails to capture, it throws away these time relations, or obscures them at best.

@Jimmy Miller

Then there is the question of “inline” documentation vs non-inline. That of course is a distinction based on the interface we use. In an image based format, that can be configurable in a way text tools don’t traditionally expose.

True in theory, but limited in practice, in my experience. Inline documentation (e.g. comments in code) is often written in such a way that it only makes sense in a given place. Example: "The two following lines initialize the frobnicators defined in class Foo."

Yeah I agree. My point really was that text file based vs non-text file based seems to make little difference. I was trying to give it credit for at least on difference, but you negated that :)

Yeah, I’m not at all a fan of formalizing these processes. So your otherwise, rephrased, is exactly what I’d advocate for. Let each programmer decide how they want to comment things. Let peer social processes (not power relations) influence and change how that works over time. Uniformity in programming is vastly over-rated, in my view.

I've heard this before and I disagree. I just came across some code where a programmer was just ranting in the comments about code quality. Not only was this low value, but it could be considered harmful or abusive to someone that wrote the code. I would have rather they refactor this code if it was bothering them, or worst case say "TODO: Refactor" or something than a multi-paragraph sarcastic rant. I've seen this a lot in code. This code was (theoretically) reviewed and approved. Do what you want anytime can lead to organizational issues, bullying, fighting in code reviews over what a "proper" commenting is. It's a lot of overhead and power dynamics come into play. I like to avoid this if possible

We have the same goals here, but I have seen the exact opposite reason for organizational, issues, bullying, and fighting in code reviews. In the places I’ve work these formalized processes are the tools people with power, or clout, or whatever use to bully others. They are the tools used to make toxic work environments, to declare those with minor disagreements to be troublemakers. I see no reason that I’d have a major disagreement with anyone in this thread. All of the opinions expressed here are opinions I’ve seen echoed by coworkers that I’ve worked closely with, without formal agreements on these things. We always came to a nice happy medium. Formalization works really well for those in power. Those who get to make the formalization. But it is also a sure fire way to make it so voices in the minority are not heard and that progress becomes much harder. Are their downsides to informal processes? Absolutely. But I’ve definitely had the opposite experience to you. Especially in large code bases maintained over many years, formalization prevented time and time again improvements most agreed should be made.

Yeah, there's something here that you can't encode. All organizations have to trust people in some ways, and have social rather than technical guardrails for it. Good organizations have good social guardrails. It gets nonlinearly more difficult to pull off as the group grows.

Another case of emergent vs. imposed rules. One reason why we have mostly imposed rules in social systems is power relations, but that goes both ways: power relations come from the necessity to impose rules because we don't know how to manage emergence well enough in larger social systems. I'd say the ideal to aim for is formalization through consensus. But we lack efficient consensus formation processes (as far as I know).

@Jimmy Miller I think we have different definitions of formalization. Most places I've worked had a written coding standard, which can also define comment guidelines. This can come from top down, of course, but it can also come bottom up from individual members of the team. Large company wide coding standards should still accept feedback from individual ICs that bring up issues, and for things that are under-defined individual teams can define them for their codebase or use case if necessary. Defining "what a good comment" is in every code review on a case by case basis is not productive, although obviously in some cases it will need to be addressed. I don't feel like I'm advocating for anything unusual. Written coding standards, document your code, a linter. I'm just going to accept I'm an outlier here and that might be due to social, cultural, or experiential bias. I've never had an issue with an organizational coding standards but have had issues with individual coders in code reviews. I know you're advocated that unified coding style is overrated (another thing I disagree with :)), but even in that case, if one person is following a good practice, but the rest of the team isn't, shouldn't that be shared and adopted across the team? Slightly related, in this talk about rendering architecture at Activision (really Call of Duty engine), the CTO Michael Vance talks about documenting code (). This was a large code base that had very few comments and even deleted John Carmack's famous Q_rsqrt comment (https://github.com/id-Software/Quake-III-Arena/blob/dbe4ddb10315479fc00086f08e25d968b4b43c49/code/game/q_math.c#L560) , but very detailed comment history. It's possible that widely used tools (Git, GitHub) make this style of documentation difficult to work with, but I enjoyed it with Peforce. That's a small sample of how my career has biased my opinions on these things. So, yes it sucks that you have had leadership that forced formal processes on you that didn't work, but my experience has been the opposite, I've experienced more challenges with peer to peer interactions than with company or team wide process.

@Scott Anderson I really liked your comments yesterday, but your example today of Google's style guide has always felt to me like a case where formalization is misplaced. It's just so focused on nitty-gritty. I really got radicalized against style guides by my time at Google, where I consistently found engineers falling into two traps: • Assuming that code was well-architected just because it satisfied the style guide. Style guides were meant to focus code review. In practice they provided cover for rubber-stamping. They also short-circuited critical thinking. (How could my code possibly be good, if it violated the style guide?) • More subtly, thinking of code as an asset rather than a liability, so that it felt better to have more of it. Of course, Google has more fundamental issues of incentives, so it's hard to blame the style guide too much. Perhaps it was just the sharp end of the spear for many of my worst interactions. I'll just suggest that style guides become counter-productive when they outlive their creators. We were living in a world of received wisdom without the means to change it. That sense of disempowerment is far more important than any benefits in consistent code style. Bringing it back to my original point, these recommendations are highly situational. I find it impossible to recommend practices in all situations. All I can do is recommend you minimize scale. Because then at least you have a chance at a coherent good/bad evaluation for everyone in a specific situation.

@Kartik Agaram both of those are real issues. I did not think of the a style guide encouraging those behaviors, but more of a way to get past (most) questions that may come down to opinion in reviews and focus on architecture and the problem the code is solving

@Scott Anderson

I think we have different definitions of formalization.

Your definition is exactly what I’m talking about. I’ll start here with the meta point and get back to the code/comment standards more directly in a second.

This can come from top down, of course, but it can also come bottom up from individual members of the team. Large company wide coding standards should still accept feedback from individual ICs that bring up issues, and for things that are under-defined individual teams can define them for their codebase or use case if necessary... So, yes it sucks that you have had leadership that forced formal processes on you that didn’t work, but my experience has been the opposite, I’ve experienced more challenges with peer to peer interactions than with company or team wide process.

What you are saying here is exactly how I’ve seen it done too. It has not been the case that leadership forced formal processes that didn’t work. They were all ICs who made these standards. But typically they were more senior engineers/architects. I’d imagine that is fairly standard. And it might sound crazy, but I think these are major problem. First, power isn’t about leadership or non-leadership. People can have power over you without being above you. The people who put these coding standards in place are deciding how you ought to work. Perhaps they are right, this standard is good, or at least good enough. But what does that matter? What problem are we trying to solve by forcing people to cohere to a certain standard? Are we trying to, stop that person who leaves rants in code? Are we trying to stop the annoying code reviewer who nitpicks every little thing? If so, those are great goals with a bad fix. Changing the rules isn’t fixing the problem. Those people still have those bad beliefs that cause them to want to have that behavior. If there is someone leaving rants in code that are disrespectful, shouldn’t some one talk to them? T.S. Eliot wrote some very poignant lines about this about people who

constantly try to escape

From the darkness outside and within

By dreaming of systems so perfect that no one will need to be good.

We do precisely this constantly. Make system so that people don’t have to be virtuous. People don’t have to have informed opinions, they just have to follow the rules. I think this impulse is one of the ways we have stopped engineers from thinking. It is one of the ways we prevent people from taking rational approaches to their opinions on things like commenting. (And by rational, I mean a process that involves reasons, not that the outcome is correct. You can be rational while being completely wrong and vice versa.) Quickly skimming the c++ style guide you linked, it seems like a sensible set of advice. Nothing too objectionable there. If a team of peers wants to say, “we are going to try to follow this”, great! But what I see lacking there is why. For example:

Function comments should be written with an implied subject of This function and should start with the verb phrase; for example, “Opens the file”, rather than “Open the file”.

I can imagine reasons why you might want to make this a rule. Let’s say you are making comments for some sdk to be used by the public, that seems like a sensible bit of consistency you might care about. But this style guide is completely void of that context, it gives no reason why at all. So, to summarize. I have no problem with linters. I have no problem with style guides. I have no problem with documenting code. I have trouble with imposition. It is more important to me that people come to considered, rational opinions. Imposition does not produce that. To highlight this, let me get back to the main topic more directly.

if one person is following a good practice, but the rest of the team isn’t, shouldn’t that be shared and adopted across the team

Yes. It should definitely be adopted, but only if the team is convinced. Only if the team believes that this is the better way forward. Even if it is a fact that this practice is good, just adopting it by fiat does not accomplish my goals. Sidenote: I do like the commit message style of expressive documentation. I do that myself quite often. Even if I don’t know that people see it or not, it has helped clarify things for myself, even has helped me discover bugs. I’ll take a guess as to what the disagreement is here. I don’t think we’d actually disagree much in practice when it came time for code review. I’m not for long ranting comments. I’m not for nitpicking things. I try to stick with the standard formatting and styles of a community (depends on the language and code base). I agree that code review should transcend style and should “focus on architecture and the problem the code is solving”. What I think we are disagreeing on is he end goal. I really don’t care about productivity. I don’t care about efficiency. I don’t care about consistency. I care that programmers are getting to express themselves. That they are learning. That they are thinking through things. That they are building things that aren’t a pain for others. That they aren’t imposing on others. That they are grounded in the concrete situation of the codebase, the system, and the world around them. That they are building a theory (see Peter Naur’s Programming as Theory Building). These imposition of things like comment and coding style are admittedly small things. They are not a hill I die on. But to me the are emblematic of these larger issues.

That Elliott quote is great, as is the point about recording why. Style guides are a hill worth dying on precisely because they're emblematic of larger issues. A rule that isn't owned by somebody who encourages debate about it (debate that comes from shared goals about getting something done, not for its own sake) is organizational debt, analogous to tech debt. (Where goals are not shared, there be the dragons. Hard problems nobody seems to have good answers for today, as far as I can tell.) Even though we're well past the age of the organization man, the best organizations grow people. You can't grow people without letting them repeat mistakes. Doing this safely without killing the org, that's the whole game. Rigid rules that prevent learning are clueless, like trying to eradicate wild fires.

So I guess the difference is I don't see it as leads/seniors forcing everyone else to there standards. I still see it as a collaborative effort but an upfront conversation including all of the team rather than a . Some people will lose out sure, but doing it ad-hoc in code reviews tends to lead to inconsistent direction based on who your reviewer is and can actually be conflicting. Imagine as a junior engineer if one senior engineer tells you "code should be self documenting, name your function better and remove that comment" and in your next review (maybe in the same code!) another senior engineer tells you "you should always comment your code, write why you wrote this". I think the core difference here is seeing any kind of agreed upon standard as not being able to express yourself (heard that before) vs not having a standard as a way to foster bullying, toxicity or confusion in reviews

I'm not saying we agree 😛 I think you have half the story. But yeah, I'll shut up now. Clearly I have some scar tissue here, and this is possibly off topic for this forum.. Oh, one hopefully final edit: "up front conversation with the whole team" is 👍🏼👍🏼 But that is not the state of the Google style guide.

Are you also against languages with idiomatic styles and standard linters, or even having linters at all?

Sorry to pile on 2 against 1, sometimes I don't know if you're asking me. But in case you are: I don't care too much about the "expression" framing. And yet, I hate Go :) Particularly the prohibition against unused variables.

Not sure if the going in circles here was about me or Kartik. (or both) But I don’t think inconsistent directions are bad. Yeah, absent any direction, encouragement, mentoring, etc a Junior Engineer being told conflicting things can be terrible. But my fix isn’t to stop the inconsistent direction, but rather to help the Junior Engineer understand why they are getting that inconsistent feedback. And what to do with it. If those engineers are trying to impose their view on that Junior engineer and block code review of silly matters of opinion, also go talk to them. I think both standards and non-standards can lead to bullying. I have seen both lead to bullying. I think that issue is completely orthogonal. We can stop bullying    by reforming bullies or getting rid of them. So maybe that is a point of disagreement. I definitely don’t think what I said is just about limiting expression. That is definitely one thing. But this of expression I’m talking about is different. I don’t think following a style guide or having a linter is an imposition on expression. My point about expression is about power and the ability for people in power limit discussion by imposing rules. Not that I want my code to look cool or do hacky things a linter would yell at me for. This is about institutional structure not about how the code looks. You said you don’t see it as lead/seniors forcing everyone else. I do. I think that is our disagreement more than anything. I think people with more power than you declaring rules you must follow is not a good pattern to establish. You see it as a debate. I see it as an imposition. To me, debates are about each side learning, not declaring a winner and a loser. We can debate code style without having to make rules in the end. That is what I’m for.