3 ms·
That is how I feel about these comments. In a vacuum I like them and when I bump into a piece of 10 year old code commented like this it is great. There is on
by tempest_ 5y ago
That is how I feel about these comments.
In a vacuum I like them and when I bump into a piece of 10 year old code commented like this it is great.
There is one caveat however, they have to be meticulously maintained and always updated to reflect every change made to the code. It is a huge caveat because more often than not the comments are out dated and no longer reflect the actual code and at that point they are detrimental.
- coliveira 5y agoThat's why Knuth had the idea of creating literate programs where documentation and code was maintained in a single block. Unfortunately, this idea was never used in large scale.
- kevin_thibedeau 5y agoHave you ever tried to read the soup he created with code blocks rearranged to suit the generated text rather than any future maintenance coder?
- RobertKerans 5y agoYeah, I think there's a fundamental problem with the implementation -- with small, single-file programs where the code can be written in a chronologically linear manner it works well. But with that there's no need for reordering logic, so much of the more complex parts of weaving are redundant. Scripts, for example, are pretty easy to set up as [for example] markdown files, which works great (particularly in a project that requires a set of helper scripts which need why communicated -- having a set of markdown files in a folder makes it IME much more ergonomic for other devs). Anything larger and it gets increasingly fiddly and (again IME) not worth it.