This is the name of a concept to combine source code and highly structured human-readable documentation, such that the main artefact is the documentation, and the secondary artefact the full source code extracted from it. Any change to the source means changing the explanatory documentation of the goals and reasoning at the same time. It was invented by no other than Don Knuth, and he, together with his collaborators, wrote the TeX program in it, to show how it is useful in practice.

I myself have used the technique in various occasions at work, for example when taking on an important but almost unreadable piece of code I inherited at work, to preparing sources for a complex algorithm for handover when I was leaving another larger project, and also in leisure coding.

The tool which is most widely used for this approach today is Emacs org-mode. It has the advantage that it works for every programming language, and you will likely find full examples for all languages you use, but many other tools (for example for vim) exist.

  • atzanteol@sh.itjust.worksEnglish
    11·
    18 hours ago

    If a function has 300 lines without a lot of supporting documentation then I doubt that it is “clear, readable and concise” anyway.

    Code - not function. Files often have multiple functions in them. If you can’t read and understand code - I don’t want you on my team.

    I have never found it hard at all to skip past comments that are not relevant because my code editor helpfully colors them differently from the rest of the code, making it easy. Does your editor not do the same?

    If it’s something people will simply skip over then it’s not useful. Don’t pollute code with tons of unnecessary comments that you think will be useful for some “perceived future”. They just add to your maintenance work.

    Write your code to be understandable and document the architecture/design separately.

    It depends on what you are doing. If you are implementing relatively simple logic like a REST API handler, then it is probably overkill. If you are implementing a relatively advanced algorithm, then having a running narrative of what is going can be extremely helpful.

    Agree - most code is pretty straight forward. Save the comments for where it’s needed.