Hacker News Reader

That sounds a bit like Donald Knuth's method of literate programming: https://en.wikipedia.org/wiki/Literate_programming

"The literate programming paradigm, as conceived by Donald Knuth, represents a move away from writing computer programs in the manner and order imposed by the computer, and instead gives programmers macros to develop programs in the order demanded by the logic and flow of their thoughts.[4] Literate programs are written as an exposition of logic in more natural language in which macros are used to hide abstractions and traditional source code, more like the text of an essay."

I would go so far as to say it is literate programming. People tend to think literate programs require an extensive system to support them, such as org-modes's emacs integration, or weird meta-programming facilities, but the truth is a program written in any language that support comments can be literate programs, so long as the content of the comments dominates and dictates the structure of the code -- which is exactly what GP commenter's method sounds like.

> so long as the content of the comments dominates and dictates the structure of the code

The key feature of literate programming is separating the order that code is written in from the order that the compiler requires, not comment to code ratio.

As conceived by Donald Knuth.

Literate Programming as conceived by codemonkey-zeta is as described above.

> The key feature of literate programming is separating the order that code is written in from the order that the compiler requires

But what's the purpose of divorcing code execution order from the machine, and instead tying that to prose? It's simply to facilitate the reader's understanding of the logical structure of the program without the superficial parts.

Just because you do discuss those superficial features with the "literate-programming as code comments" paradigm doesn't make the program less literate, it just means the prose has to be less efficient.

I do agree it's better to use a system like org-mode for literate programming because it is better to separate the description from its execution, but I'd argue it isn't really the essential element of literate programming.

> It's simply to facilitate the reader's understanding of the logical structure

I completely agree. You can present the material in reader order, not program order.

"The key feature of literate programming is separating the order that code is written in from the order that the compiler requires"... in the languages that were popular at the time Knuth wrote the definition, which were very rigid and uncompromising on layout.

We don't need specialized literate programming tools today because modern programming languages are already capable out-of-the-box of sufficient flexibility in organization that the additional marginal benefit of a superspecialized higher-layer toolset to weave pieces together is no longer worth the effort of learning and propagating out to teams. Yes, they technically can do things programming languages can't, but I could even honestly quibble on whether those things are a good idea.

This is why strict Knuth-ian "literate programming" has never taken off on a technical level and why it never will; by the time it might have gotten enough attention to really take off, programming languages had already largely incorporated the necessary additional flexibility that made it unnecessary to use specialized tools to write good code.

The human reason, of course, is that merely making documentation easier or nicer is not generally enough to get people to write it, and arguably literate programming makes it harder to write. Not because of the tooling being bad or anything, but because of the bar being raised really high to have "proper" documentation under its dictates. People can write plenty of well-documented, high-quality code in any modern language right now. They just generally don't.

You are certainly correct that older languages had more constraints on ordering, but I completely disagree that modern languages have removed all restrictions. I assume in whatever language you are imagining you have things like methods in classes or namespaces. This forces you to write them all together. The ability to separate those out is powerful.

As evidence of this, compare a well organized C codebase to whatever language that you have in mind. Does it really look that different? Literate programs on the otherhand do like quite different.

Furthermore a big programming project is still just a list of files. What do you read first? What are the important concepts? There is nothing to tell you this information in a typical program. A literate program has a page 1 and you start there. You can think of it like the difference between API documentation, and a well-written tutorial. Modern code files are great API documentation, but are lacking in that other form of presentation.

Another feature modern languages don't have (and probably shouldn't) is the ability to integrate other media types into the code (images, math notation, etc). This is another feature facilitated by literate programming systems, although not the essence of it.

"I completely disagree that modern languages have removed all restrictions."

So do I. That's why I said the marginal advantage makes it not worth it, and said already that literate programming does things that conventional doesn't.

(If you don't know what a marginal advantage is, you may want to poke around on the internet a bit. It's a very valuable concept. And I see a lot of people using the word in a way that shows they don't really know what it means; it is commonly thought that it means something "small" or "insignificant". That's not what it means.)

"There is nothing to tell you this information in a typical program."

This is true, but it's not true because nobody uses strict Knuthian literate programming, it's because nobody is writing those. Languages generally do have a place to put a top-level summary and organize all the rest of the documentation. I know; I use them and write them. All my major systems have an official "top level" location, and generally I put it in the local system's language-specific documentation format (godoc for most of my systems). People just don't write them. Handing them better tools won't solve that problem.

I do this too, and it’s great. I’d much rather rewrite a comment six times and then write a function once than rewrite the function and re-modify all affected code six times.

Also, difficulty writing a clear, concise comment is a strong code smell indicating that you don’t sufficiently understand the following block of code. Much better to realise this at the comment stage than at the debugging stage.

> I’d much rather rewrite a comment six times

Yes! Rewrite that comment until it's sound! Being able to write in spoken language what the code is doing is so often related to the writer's ability to write that code succinctly.

I did this early in my career then stopped when I realized it generally made the code less readable. Generally, not always. Sometimes a comment about what the code does is invaluable if it’s complex, but usually it is redundant with reading the code directly. I feel like coming across code littered with comments about what the next line does reflects someone not cleaning up after themselves, a string of trivial comments would not pass code review on most teams I’ve been part of.

This applies to comments about single statements in the code, unless they have an esoteric side-effect or there is a particular why that needs to be explained.

But comments that describe a paragraph/block of code have a separate value. Being able to skim code faster because of a series of well chosen sentences is an aide beyond clear code. As the OP described it is a good way to design before the code is written.

Very similar situation here. I have always approached my code, my codes documentation, and the actual user documentation with this attitude: I assume that someone in the future looking at it will be on their first day on the job, and may not be familiar with the context I am so familiar with.

Comments on non-trivial code is invaluable. I do it constantly and appreciate traversing previously made comments, especially when beyond short-term memory. Regexes, multi-conditionals, all those weird edge cases. How does any of that go "out of date"? As time progresses, comments become _more_ valuable, not less. What is the use case where comments are bothersome or out of date?

Comments about what something is doing are both the least useful and most likely to go out of date.

Comments about why something is happening are in my experience much more useful.

An example:

# Using an if / elif rather than a select here

Rather than:

# Use a large if / elif statement here due to a regression in TCL 8.4 which made select statements significantly slower. See GitHub.com/tcl-bugs.

For figuring out how to build complex systems I’ve started doing something like this too, but in prose form, in a separate document, purely as a form of thinking through how the pieces will all fit together. Most recently, it was for building a multitrack video player, and working out how to organize the various parts (decoders, mixer, compositor, player, handling seeking, etc etc). I drew out a TON of block diagrams while constantly feeling like they were missing the how and the why, and then I sat down and wrote out my thoughts it helped a lot with getting clear on how it would work.

I've been doing this for decades. Possibly influenced by beginning my career coding in assembly, os possibly by Knuth.

I do the same thing. I then replace the comment with a method name that describes exactly what the comment described, e.g. _getLowestFooIdFromBarCollection(). I then implement the code inside this private method.

Similar to my strategy. Write the code as if I had all these magic functions that did steps:

    def write_report():
        db = connect_to_database()
        data = get_data(db)
        summary = summarise_data(data)
        save_report(summary)

After this, do the same for each of these functions.

I do pseudo code sometimes too. I notice that your functions/methods/whatever are verbs that are assigned to nouns. It reminds me of:

Verbs in Javaland are responsible for all the work, but as they are held in contempt by all, no Verb is ever permitted to wander about freely. If a Verb is to be seen in public at all, it must be escorted at all times by a Noun.

http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom...

Here's to looking at you `get` and `set` decorators.

Top down design is great.

Especially in Haskell where you can stub those functions as undefined and get type checking along the way.

I’m not too lazy for comments, but I hate it when the flow of explanation/logic gets piled up with details, all in the same visual style. A source becomes a lenghty book with randomly discussed topics mixed with code. Instead of comments I’d like to emphasize some parts and write irrelevant details and technicalities in a smaller font with a lower contrast. And/or collapse parts of it, but with manual collapse statements, not whereever program syntax allows (I find this completely useless). Also abbreviate expressions into comments that by default replace them completely. E.g.

  <cycle through params and start a service for each one>
  …
  <set up an ocr subprocess and handle errors>
  …
  if (<is a numeric string>) {
    <trim whitespace>
    <extract integer part>
    <send it to /path/to/route>
  }

expands into a corresponding full-page code and more details when you click on these parts. Can’t simulate fonts and colors on HN, sorry. This isn’t exactly literate programming, but more like a programming markdown. I wish it was every language’s way to go. I know you can simulate that with functions and IDE, but having a continuous context has its own benefits (you don’t have to pass it around, which is tedious and again technical), and also naming things properly and in a unique non-polluting way is hard.

I ran into this issue and have settled on very descriptive naming for variables, functions, classes, objects, what have you. I still comment a lot, but it's things you might not infer from the naming conventions. Even when I don't think anybody will ever see the code I do it this way because when I open it up a year later to expand, between the git logs and my comments I'm ready to rock right away.

> I ran into this issue and have settled on very descriptive naming for variables, functions, classes, objects, what have you.

readingCode likeThisKind reallySeemsTo absolutelyDdosMyBrain especiallyAsTheNamesGetLonger.

There are TwoHardThings. I'll take longer descriptive names any day. There is a discussion whether the prefix of words like "get" (i.e. `getName()`) is necessary. Please keep as rare as possible the describing of the _type_ of object, like `MyDataDTO`, `ListOfPeopleArray`, `ApiRequestObject`.

This is slightly different from my idea. I also comment a lot, create sections of code and use names which at least I can pick up later. My issue is not with names (words), but with a structure of text. A wall of it is “either read or go away”. I’d like to see through it as if it was a high-level description and only dig into details when required. This comes from an observation that you perceive best what’s on the page when you don’t have to jump around and collect knowledge. A page is a best perception unit. Everyone talks about good descriptive names, but then you open any project and see verbAdjNouns at best, which implies that you are familiar with their pretty local jargon.

it is natural that the first language you would choose to write your program in is something that you can natively compile.

I definitely do this as well when I have a complex feature or pattern I need to implement. It’s best to break down the problem into solvable chunks and writing the comments out first helps you break it apart and also make sure you haven’t missed anything.

This is the stuff that a software engineering professor will tell you to do, you ignore it for years, and then later on, after you’ve matured, you find yourself picking up again because it’s just one of those incredibly simple and responsible ways to break down complex problems.

I've also hit on doing this as well. I find it really helps to organize my thoughts, uncover edge cases, etc before I start to write code.

Then I might start sketching the implementation with function signatures docs, types, loops and calls, and gradually start filling it in beginning with the parts that are less clear to me.

I do the exact same thing. Psuedo code it up and that's my comments basically.

> It helps me put myself into the shoes of the caller reading that documentation without knowing the implementation details.

I program the same way and wish more people would consider the audience when writing code.

Usually, when I do this, I immediately end up with a comment that doesn't reflect the code, and is cut and moved around so many times that it's not legible anymore. So I try to replace the comment with code, at once or piecewise (on what case, the comment doubles as a TODO list) during the process.

I believe "TODO" comments are valuable and should be left in; it shows the author also understands there's a better way, once it's viable. Most of my professional colleagues do not agree. I swear it's an ego thing.

I believe this is due to how IDEs have introduced useful features to elevate things like specific comment structures like TODO into something "official" and recognized and reported on.

So things like a quick "let's improve this part later, but this is fine for now" become items that are highlighted as not "DONE" and then are seen as eyesores or unprioritized tickets, which leaves a bad feeling for devs.

While I think these features of automatically tracking TODOs can have their uses, like most things if they become metrics they start to lose their value. Sometimes it's better to just have a keyword you can easily grep for when you do find some time, having these results show up as cases against your abilities to finish the work is unhelpful, but that's what the manager and maybe coworkers see, unfortunately.

Hum... Your comment reads like "I have this very specific and subjective process that works for me; people that do things differently are too egocentric to notice their incompetence". Your colleagues may react badly to that style.

I believe (but I'm not sure) I do get what you re trying to say, but not every TODO reflects some eternal trade-off. Some are for real clear improvements (like the "there isn't any code here" into "the code was written" on my example) whose history won't add any value after they got done.

Like TDD-lite :)

Sounds like software design process done poorly

Can you elaborate on that?

Code comments are implicitly associated with code that already exists. Sounds like your making a presumption about what code exists and potential missing the forest for the trees.

>> it’s usually the code that needs fixing

On larger teams the likelihood than comments get out of date is probably higher - particularly if the original comment was very long and detailed and the original author has moved on.

The number of times I've seen obscure code that would have been elucidated by a good comment is vastly higher than the number of times I've seen outdated comments.

Funnily enough, most of the outdated comments I can remember were dead docs links despite that being a very common 'solution' to the problem of outdated comments.

My experience is the opposite for the most part.

We might read different kinds of code, perhaps? I do lots of systems work where obscure hacks to work around toolchain and hardware issues are common.