Hacker News Reader

Comment by IncRnd | Hacker News Reader

> Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading.

This is fine for writing business logic, but this is not good for domains that require insightful code in order to execute within certain time constraints. Some problems require domain knowledge and expertise, which means that you cannot as easily hire and treat programmers as replaceable commodities of junior level people.

View on HN

Code that's under time constraints especially needs good documentation. Do you still know the constraints of code you last touched 5 years ago? I don't.

As for your comment about the commodities. Yes, it makes it easier to onboard people, but by this, employers also make it easier for people to switch jobs and negotiate better terms. So I don't agree that this necessarily creates a worse situation for employees.

Do keep in mind that there's a difference between reading and writing code.

You might very well need experience and domain-level knowledge to write the code, but often you can still make it readable to beginners.

Of course, 'often' doesn't mean always. See eg https://en.wikipedia.org/wiki/Fast_inverse_square_root for an example of code that falls in this gap.

Yes but this can be harder than writing good documentation along side the code. For example I work with software that automates CAD manufacturing. Knowing what side of the part is side A is hard to communicate. But we have drawings that help explain it all. I've yet to find a way to have this embedded into the code. Asci art comments are as good as I've gotten.

Donald Knuth thought about this problem before:

https://en.wikipedia.org/wiki/Literate_programming (and https://wiki.c2.com/?LiterateProgramming)

> Asci art comments are as good as I've gotten.

This is good, and people should use it more. But, to go further than that, I recommend:

- Setting an official, designated place for rich documentation related to code. A wiki, or a folder in a repo, or a separate repo - either works, as long as every developer is made aware the thing exists and is important.

- Put references to documentation in that place in your code comments.

Having done that, you can now put in your comments things like:

  // Which side is 'A' and which is 'B' is determined by
  // Some Method. The code below implements this logic.
  // The exact explanation (with diagrams) of the method can
  // be found in docs:/Algorithms/Some Method.docx

Of course, that documentation storage place needs to be treated as an extension of the code repository - i.e. devs should have the same access rights (both technical and cultural) to it as they have to the codebase, so they can both peruse the documentation and keep it in sync with the code.

On the ASCII diagrams, it might be worth checking if your specific case allows richer content to be embedded in code comments directly. For example, in the past, I worked in a Java shop, and realized I can embed images in the comments - the IDE I used would parse data URLs (like: "data:image/png;base64,iVBORw...") in one JavaDoc tag (don't remember which) and render the image in the tooltip! I only ever did embed a cat picture like this, because I soon realized not all Java IDEs will display the images - but if your team standardized on tooling that can handle it, it's an easy way to sneak in proper diagrams.

It would be great if IDEs came with PlantUML support in code comments - there's a bunch of diagrams I have now that I'd love to embed in the source code, but can't, because nobody else can make their tool handle them automatically.

(In general, it's worth investigating team/tooling-specific options you have for quality-of-life enhancements. For example, even though everyone in my current team uses different tooling for C++, they all use the same debugger - the one in Visual Studio. So I started producing Natvis definitions for some of the complex types we use, as well as error codes from proprietary APIs. While not exactly documentation, they remove some type noise and save you from searching for error codes.)

Not sure which language you use, but At least in java you can embed images into the javadoc comment and they get rendered by the IDE when you hover over a method or class. Comes in handy when you need to describe Boolean mesh operations for example.

Make code obvious such that someone else tackling the same problem could write the same obvious structure and solution. Writing the naive code first, then optimizing, makes it more obvious how to accomplish this, including non-obvious comments and references.

So make code obvious first to reduce WTF's later.

This never works. You cannot iteratively progress from a wrong algorithm to a good one in general. You can maybe optimize things by cutting off problem space, but that does not actually work in many problems.

For example, quicksort and radix sort have nothing in common besides ordering things. Likewise treating a tree like a general graph won't get you to a B-tree. Trying to simulate behavior of an array with a single linked list requires an expensive and smart memory allocator. Etc.

It gets even more complex if we're talking real-time software, especially multithreaded. Single thread solution does not appear even remotely similar to a performant, concurrent, ordering tolerant code.

It is as you say problem dependent. In a high level language, you could start off with a generic std lib sort. Or you could start off with the intended sort algo and improve on it. The point is to make it more or less straight-forward and readable first. Then you find optimizations, inlining, etc., keeping intentions in comments and the like.

For multithreaded there are design and tactics that can be documented separately, as comments would probably be too spread out anyways to be too useful.

This is hard when working iteratively, as you have to work out a working solution before you know it. The problem is after tough work to end up with something working, but unreadable and less maintainable. The ideal would be to have the time to rewrite and retest, and not etch that magic brilliant code in stone. Ie. the linux kernel is a good example of code being iteratively refactored and rewritten many times. Though as you say, it'd require quite some time diving deep into such code anyway. Doing what works well should make it accessible to more than one dev.

So the point is just so that others can access and modify the code a bit easier, even for tough sections. This goes very much against the grain, because of exhaustion and not wanting to take on further risks and rework.

Thankfully, that represents only a fraction of the software engineering domain.

Also, just because it's insightful doesn't mean it should be illegible. Yeah it may go down a level of abstraction and use assembly and SIMD code, but you can then write it in that language, at that level, instead of trying to be even more clever. And of course wrap it in a function name that describes what it does, accompanied by documentation that explains why it's implemented the way it is.

True, but if the code is that subtle then you still need to write it as simply as possible, otherwise even your ever-so-clever senior programmers will struggle to understand it fully.

And unfortunately, only a tiny percentage of code in even a really interesting project will be anywhere near this tricky.

Reply on news.ycombinator.com