Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Response to “Literate programming considered harmful”

johnwshipman.blogspot.com

Post reply on HN
Print view View original

21–30 of 68 posts

Re: Response to “Literate programming considered harmful”

#21

Post by pjmlp »

quantumhobbit wrote: post #6

The trend in programming lately seems to be less to no comments and less to no documentation; and it is killing the joy I take in programming. Without comments the only way the next guy has a chance to understand the code is if you stick to lowest common denominator patterns and frameworks. You can't do anything that hasn't been done before. I think this is related to the proliferation of frameworks. I can't come up…

I guess that might be a trend in some inhouse development.

In our consulting projects there is always a minimal level of documentation specified by the customer as delivery artifacts.

They want to be sure the next set of guys are able to carry on when there is budget available again.

Re: Response to “Literate programming considered harmful”

#22

Post by panic »

ctz wrote: post #14
jcadam wrote: post #13

Earlier quoted context omitted.

> The trend in programming lately seems to be less to no comments and less to no documentation; and it is killing the joy I take in programming. Without comments the only way the next guy has a chance to understand the code is if you stick to lowest common denominator patterns and frameworks. You can't do anything that hasn't been done before. Enter Golang... a language smaller than even ANSI C. It's readable because…

> Enter Golang... a language smaller than even ANSI C. It's readable because if you've worked with Golang for more than a week, you basically know every language construct you'll encounter. That's not really what readability is to me. For example, I consider this idiomatic golang code (from the standard library, no less) to be entirely unreadable: https://golang.org/src/crypto/tls/handshake_messages.go#L297 For me re…

It's ultimately subjective, but I think that code is readable: the variables are well-named and each line says exactly what it does. Abstraction makes it easier for you to think you understand what the code is doing, but if you want to really understand what's going on, you also have to understand how the abstraction is implemented. Straightforward code like this can be understood directly, without having to dig through layers of function calls.

Re: Response to “Literate programming considered harmful”

#23

Post by DougWebb »

nothrabannosir wrote: post #11
quantumhobbit wrote: post #6

The trend in programming lately seems to be less to no comments and less to no documentation; and it is killing the joy I take in programming. Without comments the only way the next guy has a chance to understand the code is if you stick to lowest common denominator patterns and frameworks. You can't do anything that hasn't been done before. I think this is related to the proliferation of frameworks. I can't come up…

> I can't come up with my own pattern that best fits the problem, but I can select from a list of pre-approved patterns in our framework and shoehorn the problem into it. Generally only true for burger flipping software. If your problem is unique, there won't be a framework for it. Want to be creative? Try seeking out creative problems. Everything has exceptions, but this rule of thumb seems to apply well, in my expe…

If your problem is unique, there won't be a framework for it.

That doesn't always stop the pressure to force-fit your problem into a "preferred" framework. In a large organization, both the people defining the problem and the people enforcing the constraints on the solution can be different from the people who have to implement the solution, and may not be aware of or able to understand the mis-match.

Re: Response to “Literate programming considered harmful”

#24

Post by qznc »

wodenokoto wrote: post #2

I definitely find literate programming intriguing. I like stuff that's well documented and I find my own documentation crucial for understanding things. I am however a bit at a loss about the practicalities. Does writing a doc-string for each class/method/function and connecting to readthedocs count as literate programming?

The doc-string state pre- and post-conditions of a function and what it does in abstract terms. It should not say anything implementation specific.

For example, the doc string of "search" tells you the returned list is sorted afterwards. It should maybe tell you the complexity of its algorithm like O(n log(n)). It should NOT state which algorithm (QuickSort, TimSort, etc) it uses. Comments in the source code can explain the choice of algorithm.

Re: Response to “Literate programming considered harmful”

#25

Post by 3pt14159 »

quantumhobbit wrote: post #6

The trend in programming lately seems to be less to no comments and less to no documentation; and it is killing the joy I take in programming. Without comments the only way the next guy has a chance to understand the code is if you stick to lowest common denominator patterns and frameworks. You can't do anything that hasn't been done before. I think this is related to the proliferation of frameworks. I can't come up…

Completely disagree. I'm not going to summon up simple scarecrow arguments, but for software that makes money, I do not want your clever pattern with comments that saves a microsecond behind a 60 millisecond latency api. I want a simple for each loop. Where I want comments is where code gets hairy for a reason. For example, extra crafty SQL on some summary metrics page, sure, go ahead and comment that. But I don't want to see comments on more than 5% of a code base whose primary purpose is to make money.

And I'm not saying this because I've always had this view, I used to be too clever. I wrote a automatic caching and automatic windowing API client library. The thing was impossible for anyone else to alter because the mental model was too complex. Now I try to keep complexity only where it is needed and I try to keep the complexity quarantined from the interface as much as possible.

Huge projects like Rails can be clever while still making my life easier because they have an army of smart people finding the edge cases, but for most stuff that isn't the case.

Re: Response to “Literate programming considered harmful”

#28

Post by jcbeard »

quantumhobbit wrote: post #6

The trend in programming lately seems to be less to no comments and less to no documentation; and it is killing the joy I take in programming. Without comments the only way the next guy has a chance to understand the code is if you stick to lowest common denominator patterns and frameworks. You can't do anything that hasn't been done before. I think this is related to the proliferation of frameworks. I can't come up…

>The trend in programming lately seems to be less to no comments and less to no documentation

Hasn't this always been the case for young programmers? Seems you don't comment until you have to go back to code you wrote yourself a year later and make major changes....you then realize you should have documented it, either inline step-by-step or as a proper doxygen/javadoc style.

I can thank Dr. Leitner (CS 50/51) for enforcing comments in assignments. Took programming courses as an undergrad (I wasn't a CS major, but a Bio/Int'l studies one) in C, no documentation required...code was checked for correctness only. Leitner had his TA's go through and take off points for code that wasn't documented...which needless to say got me in the habit of documenting.

>It really comes down to laziness.

Not so sure. Laziness or lack of good habits? Perhaps a mixture of both.

Re: Response to “Literate programming considered harmful”

#29

Post by sitkack »

lucozade wrote: post #9
Apaze wrote: post #4

Is programming harmful? What question is that?! If you write malware with it, yes it is! Though not for you.

They're just using a headline derived from Dijkstra's "Go To Statement Considered Harmful". As with Dijkstra it's a bit clickbaity i.e. they really mean use with care rather than harmful. Making it a question just gives the extra benefit of making it likely to conform to Betteridge's law. So a meme win-win really.

It also conforms to Sturgeon's Law.

Re: Response to “Literate programming considered harmful”

#30

Post by cwyers »

lucozade wrote: post #9
Apaze wrote: post #4

Is programming harmful? What question is that?! If you write malware with it, yes it is! Though not for you.

They're just using a headline derived from Dijkstra's "Go To Statement Considered Harmful". As with Dijkstra it's a bit clickbaity i.e. they really mean use with care rather than harmful. Making it a question just gives the extra benefit of making it likely to conform to Betteridge's law. So a meme win-win really.

Of course, Dijkstra wasn't really clickbaiting, as clicks hadn't been invented yet.
Post reply on HN