This is exactly how I program
That sounds so painful. Not surprising it never caught on.
Why would it be painful?
You want to turn my 300 lines of clear, readable and concise logic into 1,000 lines of English paragraphs that break up the functions of my code into yet smaller pieces of code devoid of context? Now I have to dig through that book, ignoring all the shit I've read hundreds of times because it doesn't compile into anything, just to debug an off-by-1 error in a loop buried in a paragraph explaining the original developers diatribe on why we're looping over that range? Fuck. No.
This is the sort of academic crap that sounds good but in practice is just terrible for anything other than small projects that are intended specifically to teach.
You want to turn my 300 lines of clear, readable and concise logic into 1,000 lines of English paragraphs that break up the functions of my code into yet smaller pieces of code devoid of context?
If a function has 300 lines without a lot of supporting documentation then I doubt that it is "clear, readable and concise" anyway.
Now I have to dig through that book, ignoring all the shit I’ve read hundreds of times because it doesn’t compile into anything, just to debug an off-by-1 error in a loop buried in a paragraph explaining the original developers diatribe on why we’re looping over that range?
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?
(Also, by now you should be especially good at skipping past it, given that you have apparently "read [it] hundreds of times" instead of skipping past it, for some reason.)
This is the sort of academic crap that sounds good but in practice is just terrible for anything other than small projects that are intended specifically to teach.
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.
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.
Not GP, but reading gnarly code and making definitive statements about who/what/when/where/why such that your documentation is accurate, especially in a corpo context where there are not clear boundaries of responsibility, requires quite a bit of brain power. Not to mention the ever increasing entropy in systems driven by profit means that whatever you write in terms of documentation will have a pretty short shelf-life. The code might stick around as an unholy amalgamation of copypasta after a refactor or two.
I'm confused... was that wall of text supposed to have sold me on something?
I've tried this a few times. I don't think it works.
Basically the way you want to explain a piece of reasoning , and the order in which things need to be defined for a program, are different. You end up either making the document match the code structures, or the code structure match the document. Both are bad.
Literate programming tackles exactly that: You write the documentation in explanation order, and the code gets assembled in the order of a well-structured program. Have a look at the examples how this works.
It's not immediately obvious to me where the examples are.
Programming
Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!
Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.
Hope you enjoy the instance!
Rules
Rules
- Follow the programming.dev instance rules
- Keep content related to programming in some way
- If you're posting long videos try to add in some form of tldr for those who don't want to watch videos
Wormhole
Follow the wormhole through a path of communities [email protected]