6 ms·
I like literate programming in theory but the most common response I see to it is that writing self documenting code is better because as you are working on a c
by QuikAccount 5y ago
I like literate programming in theory but the most common response I see to it is that writing self documenting code is better because as you are working on a code base with many people, it is unlikely they will keep your prose up to date as the code is changed.
- Koshkin 5y agoSelf-documenting code is fine - until someone starts wondering why code does what it does, or if someone wants to generate documentation. (No, the lazy style, "OpenFile - opens a file", does not cut it.)
- QuikAccount 5y agoPython resolves this with docstrings but in general, assuming it is not self explanatory while a function exist, is it really necessary to go the whole nine with literate programming instead of just adding a few comments to explain why this exist. Self-documenting code with explanations when necessary is how most codebases already are. At least most good ones.
- falcolas 5y agoI think the one potential mitigating factor is that new features can be entirely new "chapters". Thanks to the tangling, a feature that needs to be added in 10 different places in the code can be written completely separately from the rest of the code. Additionally, bugs can be fixed in-situ, refactoring can occur at will, and neither would require the prose around them to change, since code being talked about (despite moving or undergoing small changes) still fulfills the original, documented, purpose.
- ravel-bar-foo 5y agoIt seems like adding new code as "Chapters," unless pursued with a bit of self-discipline, may result in spahgetti which is worse than a non-literate style. Imagine a multi-person project where every little feature gets its own file, and now the programmer has to find the source of the bug between interacting blocks of in code fragments split across multiple files, ehich are combined together by tooling.... oh wait, I think that describes just about any sufficiently large C or C++ project.
- admax88qqq 5y ago> unless pursued with a bit of self-discipline Any programming unless pursued with a bit of self-discipline may result in spaghetti code.
- 8note 5y agoIf you set things up well, you can avoid it for a little while - you just need the easiest hack to also be the right way to implement something
- doliveira 5y agoHow are newcomers handled in those "self-documenting codebases"?
- mannykannot 5y ago> self documenting code is better because as you are working on a code base with many people, it is unlikely they will keep your prose up to date as the code is changed. There is no reason to believe they are any more likely to keep code self-documenting (or to succeed even if they try) - it is not as if it will not compile or run unless it is. I see literate programming to be an attempt to put some rigor into the otherwise terminally vague concept of self-documenting code (conceptually, it is way beyond the platitudes in 'clean code', even though it came first.) It is, however, doomed to failure in practice because it always takes less information (and less skill) to merely specify what a program will do than it does to not only specify what it will do but also explain and justify that as a correct and efficient solution to a problem that matters. Neither 'literate' nor 'self-documenting' code are objective concepts.
- taeric 5y agoThe problem with self documenting code is that it doesn't help justify all of the parts into the whole. This is particularly troublesome in code where a refactor effectively isolated entire sections of the code, but the person that did the refactor didn't realize it, and now you have code that exists only for the sake of existing tests.
- t0suj4 5y agoI interpret self documenting as writing the what in the code and writing comments about the why. While minimizing the places where you need to explain your code. My role of thumb is that if it's not obvious why that particular line is there and removing it would break functionality, add a comment.
- taeric 5y agoI typically see "self documenting code" refer to code where function and variable names indicate the code without added comments. Think: function square(x) ... Versus function f(a) ... Often includes all functions as named things, with little to no lambda usage, since names are seen as for the programmer, not for the computer.
- t0suj4 5y agoPushing for an extreme can be counterproductive. For example completely avoiding lambda may bring the equivalent of constant abuse. Compare list.map(v => v+2) To list.map(add2) In addition to other problems with functions, you now have a potential for combinatorial explosion doing it this way.
- taeric 5y agoCompletely agreed. Though, I suspect cases like that are less common. Small adjustments by constants aren't something I do often, at least. (That is, this is a bit of a straw man.)