7 ms·

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 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 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. We only hire people familiar with the framework, so no need to document. It really comes down to laziness. A literate program demands you put forth the effort to understand it and read the docs and code. Whereas a with a framework program you can copy and paste code from blog posts and stack overflow without any clue what is really going on.

nothrabannosir 10y ago
> 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 experience.
- bunderbunder 10y ago
  If your problem is unique and requires creative solutions, and you work in an anti-documentation team, that's when things get truly nasty.
  - qznc 10y ago
    Elsewhere known as "Academia" ;)
    - Chris2048 10y ago
      Which also can create documentation without code :-)
- DougWebb 10y ago
  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.
nambit 10y ago
I have to disagree with this. I've not found anything of the sort you describe here. If you have some esoteric pattern in your code, then it's never worth the tradeoff between readability unless it is better performance wise. Calling them the "lowest" common denominator patterns instead of best practices is being dishonest.
- sitkack 10y ago
  > some esoteric pattern I have been at many sites where "esoteric" means things like first class functions (Python) or recursion. Not some hipster monad, y-combinator or method missing bullshit.
- pdpi 10y ago
  There's a middle ground between cookie cutter and esoteric. While the OP's tone is perhaps a bit harsh, I've been in his shoes before, where a team that doesn't understand why a problem doesn't fit their go-to solution forces you to write a convoluted mess to shoehorn the problem into the solution. performance isn't even the problem, usually. Maintainability is.
jcadam 10y ago
> 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 if you've worked with Golang for more than a week, you basically know every language construct you'll encounter. As an aside, I've found Clojure to be one of the most "readable" languages I've ever seen, in that I can usually just go to the source code if I'm trying to figure out how to use a library I just pulled in from clojars.
- ctz 10y ago
  > 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 https://golang.org/src/crypto/tls/handshake_messages.go#L297 For me readability is more about suitable levels of abstraction. Languages can affect that by making abstraction longwinded, or expensive at runtime, or hard to compose.
  - panic 10y ago
    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.
    - catnaroek 10y ago
      If you think that code is readable, could you correctly write all pre/post-conditions in between statements?
rtpg 10y ago
Even in the bog-standard sort of software I write, I rarely find that choosing and applying a pattern is "mechanical". Even if you tell yourself "oh, I'll use Observer", there are still so many details that can make your solution be boring and alright, or actually clean and magical. Foresight into how your structure will evolve, making things easier to test and read, separating the _right_ concerns. I have copied stuff from Stack Overflow but always for solutions to a couple lines of code. I don't know what Stack Overflow answer I can copy for the general structure of my code...
pjmlp 10y ago
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.
3pt14159 10y ago
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.
- Chris2048 10y ago
  > 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 Is that not a strawman argument?
  - 3pt14159 10y ago
    You are right, that isn't worded the way I intended (not the least because I misremembered the name). I meant to say code examples. For example: # double the counts. counts.map! { |count| count *= 2 } Is the type of strawman I intended to avoid.
    - dllthomas 10y ago
      I once saw using namespace std; // using namespace standard
jcbeard 10y ago
>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.
- levelist_com 10y ago
  Funny enough, I had a C & C++ prof deduct points for comments with the argument that they were redundant and that the code should be self documenting. Then again, this is from a guy who never handed back assignments until the end of the semester and by then couldn't remember why he graded you the way he did. Would just respond with "you didn't understand the material".
  - jcbeard 10y ago
    that's crap. self documenting code sometimes works...but not always. I love people that hand me HDL and say "it's self documenting." Then you open it, and wire names are "x_1245_to_y." Happened all the time when my students would turn in assignments. That stopped after they realized I graded the documentation too :).
    - levelist_com 10y ago
      I agree and chose to take the deductions rather than avoid writing comments. By that point I had already been in the industry and I knew better; he has never left academia.
the8472 10y ago
> 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. Or - read the tests for that method. - look at the commit log and associated bugs. - use identifiers that are self-explanatory to some extent. auto-complete makes using long names manageable. - step through it with a debugger to see what it does. - use an editor/IDE that shows additional info about unknown methods, assuming a statically typed language where it has total knowledge about available types. Comments are certainly one way to understand code, but not the only way.
- Tarrosion 10y ago
  Many of the techniques you listed are subcategories of reverse engineering. In an ideal world, the code and comments are clear enough that no reverse engineering is necessary. Given a bizarre method, would you rather see a clear comment or spend half an hour stomping through a commit log?
  - falcolas 10y ago
    > In an ideal world, the code and comments are clear enough that no reverse engineering is necessary. In an ideal world, perhaps. But in the real world, the comments contradict the code, the code attempts to use a software pattern which doesn't quite fit (and thus requires a large number of hacks to make it fit), so reverse engineering is your only real choice. Aiming for an ideal world is never a bad thing, but even if I saw well documented code, I wouldn't trust it. The only difference is that after reverse engineering it anyways, I might feel a bit of surprise when I find that the comments were, indeed, correct.
lmm 10y ago
> 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. Not true. You just have to express it clearly. I view comments as a code smell - they generally indicate a part of the codebase that you know is poorly factored. If your language/framework doesn't allow you to express code clearly, get a better language/framework. Laziness is one of the cardinal virtues of a programmer.
- bunderbunder 10y ago
  It really, really depends on what the comment is saying. Comments that explain what the code is doing are usually a travesty. With the possible exception of hairy performance optimizations. Also implementations of algorithms that aren't well known -- oftentimes the original paper is dense, academic and behind a paywall, and the Wikipedia article are a muddled mess. You really owe it to your readers to give a sane and comprehensible explanation instead. Comments that explain why the code is doing what it does, though, are HUGELY important. There's nothing worse than coming into a legacy codebase and seeing it littered with obvious special cases and workarounds that are all undocumented, so that you have no idea what they're for or whether they're obsolete or not. Skipping these kinds of comments leads to inexorable technical debt, because eventually you'll end up with a codebase where everyone is afraid to change the code.
ptero 10y ago
I do not personally see this trend. In fact I see the proliferation of automatic-documenters and automatically checked minimum documentation requirements (which, as is often the case with blanket rules, tends to misfire producing volume but not quality; but this is another topic). It seems literate programming assumes that the person doing development is the same as the one reading documentation. That is not always the case. And when it is not the case, the code embedded in documentation can hurt readability. For example, I try to get all interface specs distributed, discussed and confirmed ASAP, usually WAY before the code is mature enough to be shown outside. Also, getting others to read, think about and comment on even short ICDs is difficult as is. Getting them to read early ICDs interspersed with early code? Not going to fly. My 2c.
- Jtsummers 10y ago
  I haven't figured out literate programming with a large group yet, but I do use it (with org mode) for my own projects (solo or small group). A nice thing, at least with org-mode, is that I can choose whether or not to export a particular bit of content. * This headline won't export :noexport: These are some comments for the user and maintainers of this document. Describing our formatting and practices. * This headline will export And here's the text describing some message format. And here's a table showing the layout: | Word | 12-15 | 8-11 | 4-7 | 0-3 | | 0 | WordCnt | TimeTag| ... | ... | And here's the source for this as a C struct, but it's a work in progress. So we won't export it yet. #+NAME: MSGXXX_struct #+BEGIN_SRC c :exports none typedef struct { ... } MSGXXX_t #+END_SRC No one has to see that stuff until I'm done with it. Or, other tags could be used so I can explicitly select what gets exported depending on the audience. The customer doesn't need the code (at this point). But fellow devs (local, or at partner organizations) may.
  - ptero 10y ago
    That is reasonable for a solo project, which naturally has a common style readable to the author. In my (maybe skewed) experience though once 2 or more people start adding comments on the same place of code things can get very confusing quickly -- with mishmash of different styles, commented out comments, multiple copy-paste, etc., so the only way to understand what is going on is to delete the whole Kunstkamera and look only at the code.

nothrabannosir 10y ago

> 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 experience.

bunderbunder 10y ago
If your problem is unique and requires creative solutions, and you work in an anti-documentation team, that's when things get truly nasty.
- qznc 10y ago
  Elsewhere known as "Academia" ;)
  - Chris2048 10y ago
    Which also can create documentation without code :-)
DougWebb 10y ago
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.

nambit 10y ago

I have to disagree with this. I've not found anything of the sort you describe here. If you have some esoteric pattern in your code, then it's never worth the tradeoff between readability unless it is better performance wise. Calling them the "lowest" common denominator patterns instead of best practices is being dishonest.

sitkack 10y ago
> some esoteric pattern I have been at many sites where "esoteric" means things like first class functions (Python) or recursion. Not some hipster monad, y-combinator or method missing bullshit.
pdpi 10y ago
There's a middle ground between cookie cutter and esoteric. While the OP's tone is perhaps a bit harsh, I've been in his shoes before, where a team that doesn't understand why a problem doesn't fit their go-to solution forces you to write a convoluted mess to shoehorn the problem into the solution. performance isn't even the problem, usually. Maintainability is.

jcadam 10y ago

> 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 if you've worked with Golang for more than a week, you basically know every language construct you'll encounter. As an aside, I've found Clojure to be one of the most "readable" languages I've ever seen, in that I can usually just go to the source code if I'm trying to figure out how to use a library I just pulled in from clojars.

ctz 10y ago
> 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 https://golang.org/src/crypto/tls/handshake_messages.go#L297 For me readability is more about suitable levels of abstraction. Languages can affect that by making abstraction longwinded, or expensive at runtime, or hard to compose.
- panic 10y ago
  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.
  - catnaroek 10y ago
    If you think that code is readable, could you correctly write all pre/post-conditions in between statements?

rtpg 10y ago

Even in the bog-standard sort of software I write, I rarely find that choosing and applying a pattern is "mechanical". Even if you tell yourself "oh, I'll use Observer", there are still so many details that can make your solution be boring and alright, or actually clean and magical. Foresight into how your structure will evolve, making things easier to test and read, separating the _right_ concerns. I have copied stuff from Stack Overflow but always for solutions to a couple lines of code. I don't know what Stack Overflow answer I can copy for the general structure of my code...

pjmlp 10y ago

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.

3pt14159 10y ago

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.

Chris2048 10y ago
> 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 Is that not a strawman argument?
- 3pt14159 10y ago
  You are right, that isn't worded the way I intended (not the least because I misremembered the name). I meant to say code examples. For example: # double the counts. counts.map! { |count| count *= 2 } Is the type of strawman I intended to avoid.
  - dllthomas 10y ago
    I once saw using namespace std; // using namespace standard

jcbeard 10y ago

>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.

levelist_com 10y ago
Funny enough, I had a C & C++ prof deduct points for comments with the argument that they were redundant and that the code should be self documenting. Then again, this is from a guy who never handed back assignments until the end of the semester and by then couldn't remember why he graded you the way he did. Would just respond with "you didn't understand the material".
- jcbeard 10y ago
  that's crap. self documenting code sometimes works...but not always. I love people that hand me HDL and say "it's self documenting." Then you open it, and wire names are "x_1245_to_y." Happened all the time when my students would turn in assignments. That stopped after they realized I graded the documentation too :).
  - levelist_com 10y ago
    I agree and chose to take the deductions rather than avoid writing comments. By that point I had already been in the industry and I knew better; he has never left academia.

the8472 10y ago

> 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. Or - read the tests for that method. - look at the commit log and associated bugs. - use identifiers that are self-explanatory to some extent. auto-complete makes using long names manageable. - step through it with a debugger to see what it does. - use an editor/IDE that shows additional info about unknown methods, assuming a statically typed language where it has total knowledge about available types. Comments are certainly one way to understand code, but not the only way.

Tarrosion 10y ago
Many of the techniques you listed are subcategories of reverse engineering. In an ideal world, the code and comments are clear enough that no reverse engineering is necessary. Given a bizarre method, would you rather see a clear comment or spend half an hour stomping through a commit log?
- falcolas 10y ago
  > In an ideal world, the code and comments are clear enough that no reverse engineering is necessary. In an ideal world, perhaps. But in the real world, the comments contradict the code, the code attempts to use a software pattern which doesn't quite fit (and thus requires a large number of hacks to make it fit), so reverse engineering is your only real choice. Aiming for an ideal world is never a bad thing, but even if I saw well documented code, I wouldn't trust it. The only difference is that after reverse engineering it anyways, I might feel a bit of surprise when I find that the comments were, indeed, correct.

lmm 10y ago

> 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. Not true. You just have to express it clearly. I view comments as a code smell - they generally indicate a part of the codebase that you know is poorly factored. If your language/framework doesn't allow you to express code clearly, get a better language/framework. Laziness is one of the cardinal virtues of a programmer.

bunderbunder 10y ago
It really, really depends on what the comment is saying. Comments that explain what the code is doing are usually a travesty. With the possible exception of hairy performance optimizations. Also implementations of algorithms that aren't well known -- oftentimes the original paper is dense, academic and behind a paywall, and the Wikipedia article are a muddled mess. You really owe it to your readers to give a sane and comprehensible explanation instead. Comments that explain why the code is doing what it does, though, are HUGELY important. There's nothing worse than coming into a legacy codebase and seeing it littered with obvious special cases and workarounds that are all undocumented, so that you have no idea what they're for or whether they're obsolete or not. Skipping these kinds of comments leads to inexorable technical debt, because eventually you'll end up with a codebase where everyone is afraid to change the code.

ptero 10y ago

I do not personally see this trend. In fact I see the proliferation of automatic-documenters and automatically checked minimum documentation requirements (which, as is often the case with blanket rules, tends to misfire producing volume but not quality; but this is another topic). It seems literate programming assumes that the person doing development is the same as the one reading documentation. That is not always the case. And when it is not the case, the code embedded in documentation can hurt readability. For example, I try to get all interface specs distributed, discussed and confirmed ASAP, usually WAY before the code is mature enough to be shown outside. Also, getting others to read, think about and comment on even short ICDs is difficult as is. Getting them to read early ICDs interspersed with early code? Not going to fly. My 2c.

Jtsummers 10y ago
I haven't figured out literate programming with a large group yet, but I do use it (with org mode) for my own projects (solo or small group). A nice thing, at least with org-mode, is that I can choose whether or not to export a particular bit of content. * This headline won't export :noexport: These are some comments for the user and maintainers of this document. Describing our formatting and practices. * This headline will export And here's the text describing some message format. And here's a table showing the layout: | Word | 12-15 | 8-11 | 4-7 | 0-3 | | 0 | WordCnt | TimeTag| ... | ... | And here's the source for this as a C struct, but it's a work in progress. So we won't export it yet. #+NAME: MSGXXX_struct #+BEGIN_SRC c :exports none typedef struct { ... } MSGXXX_t #+END_SRC No one has to see that stuff until I'm done with it. Or, other tags could be used so I can explicitly select what gets exported depending on the audience. The customer doesn't need the code (at this point). But fellow devs (local, or at partner organizations) may.
- ptero 10y ago
  That is reasonable for a solo project, which naturally has a common style readable to the author. In my (maybe skewed) experience though once 2 or more people start adding comments on the same place of code things can get very confusing quickly -- with mishmash of different styles, commented out comments, multiple copy-paste, etc., so the only way to understand what is going on is to delete the whole Kunstkamera and look only at the code.