[rectang]

I know this style by the name "coding in commented paragraphs". I learned about it from Damian Conway early in my career, and the idea resonated with me so strongly that I immediately adopted it and have used it every since.

I especially appreciate how under syntax highlighting the comments provide a visually offset natural language outline or summary of the code.

[tomgp]

i use this method too. my flow is typically to write the comments first then implement them. this makes it easy to find gaps in reasoning before i write code and then easy to extract functions after if things get mor involved than expected.

[rectang]

FWIW, I don't really do that. Sometimes I write the comments as I go; there is almost always a pass I make at the end as I'm preparing the material for review where I revise the existing comments and add missing ones.

I mention this because I think it's great that the commenting style works with both our workflows and doesn't really imply rigid adherence to either one of them. I suspect we would find it comfortable to maintain each others' code despite the divergence in approach.

[NicoJuicy]

Aha, i did this. Knowing a name for it makes it official to defend on PR's :p

[pineconewarrior]

I tried to find more information on this by searching for those terms and "damian conway" but came up empty. Would you mind sharing a link, if you have one?

[IlliOnato]

"Coding in paragraphs" is described in Damian Conway's book "Perl best practices" [1]

Myself I like coding in paragraphs very much, and giving the paragraphs one-liner headings (comments) definitely makes code for me more readable and easier to navigate.

I usually don't give a heading to a "paragraph" which is just one line, unless that line does something subtle. (Conway provides a definition of "subtle": if you need to think more than 10 seconds or consult the fine manual to figure out what the line does).

[1] https://www.oreilly.com/library/view/perl-best-practices/059...

[rectang]

I found a page which excerpts 10 of Conway's recommendations from Perl Best Practices (which I no longer have around). Point 7 is "Code in Commented Paragraphs", and the reasoning is about what I remember — it might even be taken from the book verbatim:

https://www.perl.com/pub/2005/07/14/bestpractices.html/#7-co...

There are other recommendations on that page and in Conway's highly opinionated book which I disagree with (it's notorious for recommending Class::Std), but that point has stuck with me.

Note that Conway's example even includes three single-code-line paragraphs, all of which are commented. Perhaps Osterhout would not approve, or perhaps he would — each of those lines includes some subtlety, and each of the comments describes the "why" not the "what".

FWIW I don't always add a comment above single line paragraphs if the comment adds nothing. But neither does Conway comment "unpack arguments" above the first line in his example, nor say anything about the return statement — which to my mind illustrates that there's some flexibility to be expected in how you apply this technique.

[pineconewarrior]

I code in this way as well, particularly when working with pre-existing, poorly documented codebases

Thanks for the link. I may have to find a copy of that book at the library :)

[HerrMonnezza]

Not sure if there's anything written on the topic, but I guess you can take a look at some of Damian Conway's public code to see it being used. For example: https://metacpan.org/release/DCONWAY/Keyword-Declare-0.00101...

[pineconewarrior]

Thank you for the link. I'll check it out!