To me, the first (by Brooks) seems to be about grasping the domain model to understand what the system does (or can do) in general.

Wheras the second (by Torvalds) seems to be about how best to organize data in code for efficient processing. Array, hash, tree, heap, etc and their associated access time complexity. The efficiency of your solution depends on your choice of a data structure that fits the local problem.

I always attributed it to Rob Pike, but it turns out Pike's is following:

> Rule 4. Fancy algorithms are buggier than simple ones, and they're much harder to implement. Use simple algorithms as well as simple data structures.

> Rule 5. Data dominates. If you've chosen the right data structures and organized things well, the algorithms will almost always be self-evident. Data structures, not algorithms, are central to programming.

https://users.ece.utexas.edu/~adnan/pike.html

Interestingly enough, the above link has this to say:

> Rule 5 was previously stated by Fred Brooks in The Mythical Man-Month.

Which I guess references GP's excerpt.

Also says this, which kinda loops back to Linus's way of saying it:

> Rule 5 is often shortened to "write stupid code that uses smart objects".

I mean I've waded through tons of code where the original author abused strings to indicate relationships in a table - a column with semicolon-separated values referencing other tables / rows. And a ton of code to check references.

Mind you, that's more database design than data structures, but they're close enough for this example.

Self-documenting code (what I take in practice means "no comments"-culture) is something I don't understand how it can work, never seen a good implementation of it. It _can_ be successful in describing the _what_ but is poorly or not at all describing the _why_. Perhaps I'm in the wrong domain for that though.

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.

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?

To me, this feels similar to finding the correct granularity of unit tests or tests in general. Too many tests coupled to the implementation too tightly are a real pain. You end up doing a change 2-3 times in such a situation - once to the actual code, and then 2-3 times to tests looking at the code way too closely.

And comments start to feel similar. Comments can have a scope that's way too close to the code, rendering them very volatile and oftentimes neglected. You know, these kind of comments that eventually escalate into "player.level += 3 // refund 1 player level after error". These are bad comments.

But on the other hand, some comments are covering more stable ground or rather more stable truths. For example, even if we're splitting up our ansible task files a lot, you still easily end up with several pages of tasks because it's just verbose. By now, I very much enjoy having a couple of three to five line boxes just stating "Service Installation", "Config Facts Generation", "Config Deployment", each showing that 3-5 following tasks are part of a section. And that's fairly stable, the config deployment isn't suddenly going to end up being something different.

Or, similarly, we tend to have headers to these task files explaining the idiosyncratic behaviors of a service ansible has to work around to get things to work. Again, these are pretty stable - the service has been weird for years, so without a major rework, it will most likely stay weird. These comments largely get extended over time as we learn more about the system, instead of growing out of date.

I think this is a well put and nuanced insight. Thank you.

This is really what the dev community should be discussing; the "type" of comments and docs to add and the shape thereof. Not a poorly informed endless debate whether it should be there in the first place.

I recently had an interview with what struck me as a pretty bizarre question about testing.

The setup was that you, the interviewee, are given a toy project where a recent commit has broken unrelated functionality. The database has a "videos" table which includes a column for an affiliated "user email"; there's also a "users" table with an "email" column. There's an API where you can ask for an enhanced video record that includes all the user data from the user with the email address noted in the "videos" entry, as opposed to just the email.

This API broke with the recent commit, because the new functionality fetches video data from somewhere external and adds it to the database without checking whether the email address in the external data belongs to any existing user. And as it happens, it doesn't.

With the problem established, the interviewer pointed out that there was a unit test associated with the bad commit, and it was passing, which seemed like a problem. How could we ensure that this problem didn't reoccur in some later commit?

I said "we should normalize the database so that the video record contains a user ID rather than directly containing the user's email address."

"OK, that's one way. But how could we write a test to make sure this doesn't happen?"

---

I still find this weird. The problem is that the database is in an inconsistent state. That could be caused by anything. If we attempt to restore from backup (for whatever reason), and our botched restore puts the database in an inconsistent state, why would we want that to show up as a failing unit test in the frontend test suite? In that scenario, what did the frontend do wrong? How many different database inconsistencies do we want the frontend test suite to check for?

Though, interestingly enough, I have built a test that could have caught similar problems back when we switched databases from mysql to postgresql. It would fire up a mysql based database with an integration test dump, extract and transform the data with an internal tool similar to pgloader, push it into a postgres in a container. After all of that, it would run the integration tests of our app against both databases and flag if the tests failed differently on both databases. And we have similar tests for our automated backup restores.

But that's quite far away from a unit test of a frontend application. At least I think so.

It would seem that the unit test itself should be replaced with something else, or removed altogether, in addition to whatever structural changes you put in place. If you changed db constraints, I could see, maybe, a test that verifies the constraints works to prevent the previous data flow from being accepted at all - failing with an expected exception or similar. But that may not be what they were wanting to hear?

I do believe that in a lot of case an outdated, wrong or plain erroneous documentation does more harm than no documentation. And while the correct solution is obviously "update the doc when we update the code", it has been empirically proven not to work across a range of projects.

I just had a semi-interview the other day, and was talking with someone about the docs and testing stuff I've done in the past. One of the biggest 'lessons' I picked up, after having adopted doc/testing as "part of the process" was... test/doc hygiene. It wasn't always that stuff was 'out of date', but even just realizing that "hey, we don't use XYZ anymore - let's remove it and the tests", or "let's spend some time revisiting the docs and tests and cull or consolidate stuff now that we know about the problem". Test optimization, or doc optimization, perhaps. It was always something I had to fight for time for, or... 'sneak' it in to commits. Someone reviewing would inevitably question a PR with "why are you changing all this unrelated stuff - the ticket says FOO, not FOO and BAR and BAZ".

Getting 'permission' to keep tests and docs current/relevant was, itself, somewhat of a challenge. It was exacerbated by people who themselves weren't writing tests or code, meaning more 'drift' was introduced between existing code/tests and reality. But blocking someone's PR because it had no tests or docs was "being negative", but blocking my PR because I included 'unnecessary doc changes' was somehow valid.

The fact is that, when you zoom out to org level, comments do quickly drift out of sync and value, and so engineering managers must encourage code writing that will maintain integrity over time, regardless of what people "should" be able to do.

Comments allow for a high-level view of your code, and people who don't value that probably on average have a slower overall output.

I simply cannot comprehend the mindset that views comments as unnecessary. Or worse, removes existing useful comments in some quest for "self-documenting" purity.

I've worked in some truly huge codebases (40m LOC, 20k commits a week, 4k devs) so I think I have a pretty good idea of what's easy vs hard in understanding unfamiliar code.

A lot of people think comments are descriptive rather than prescriptive. They think a comment is the equivalent of writing "Fence" on a plaque and nailing it to the fence. "It's a fence," they say, "You don't need a sign to know that."

Later, when the next property owner discovers the fence, they are stumped. What the hell was this put here for? A prescriptive comment might have said, "This was erected to keep out chupacabras," answering not what it is, but why.

You might know about the chupacabras, but if you don't pass it on then you clearly don't care about who has to inherit your property.

What's amazingly funny is that many people think this is a positive, because they ascribe more value to working hard than to achieving results. I even thought your comment was going to go that way when I first read it.

Self describing code does not need theRidiculouslyLongNamesPerferredByJavaCoders.

Fairly hot take from me, life is more ambiguous than that :-).

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.

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'.

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.

[0] https://www-cs-faculty.stanford.edu/~knuth/lp.html

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.

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.

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.

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.

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.

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.

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.

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 )

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.

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.

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.

When a developer wants to switch from one area to another, they go through an accelerated program (takes only about a month).

(a) rename the column, be the guy who broke the system and spend all weekend trying to fix 6 systems he never knew existed, written in Access, Excel, Crystal Reports, VB6, Delphi and a CMD file on a contractors laptop.

(b) keep the column name, deliver the feature, go home.

(b) Go home and be happily oblivious that six other systems silently started to produce wrong results since the meaning of the column has changed. But, of course, that is someone else’s problem, some other day, when several months of reports and forecasts have to be recalled and updated.

Bad programmers chose (b). Good programmers choose (a). Better programmers refuse the change request.

Ideally the table would have been named more generically but in an earlier stage startup there will be mistakes in naming things no matter how hard you try to avoid that.

So the only thing that actually breaks here is that a small number of engineers that care about this might misinterpret what it means unless they learn the appropriate tribal knowledge. Ideally it gets fixed but if you look at all of the things that can be improved in an early stage startup, this kind of thing is pretty minimal in importance so it becomes tech debt.

In my experience, studying the database schema and IO data structures is indeed the best way to begin understanding a complex system.

Showing things acts as a forcing function to fix the thing being shown