7 ms·

Keep your source code SIMPLE

71 points by kevingoslar 7y ago

lostgame 7y ago
I couldn’t agree more. Also; keep it clean. Don’t over-comment, but comment.
- tchaffee 7y ago
  Can you define "over-comment"? Without a clear definition, it's just subjective opinion.
  - lostgame 7y ago
    Sure! The beginnings of functions, for instance, are great places to comment, perhaps even including a definition of some of the subroutines within it. In the case of an exceptionally large subroutine, commenting within the subroutine may be advantageous - but at that point you may consider another function to replace that larger chunk. Variable names that are perhaps obscure and are not practical to rename for whatever reason can also use comments. Class headers are of course also a great place to comment, to explain the purpose of the class. Good comments can lead to better code. :)
    - tchaffee 7y ago
      You didn't really answer my question though. I didn't ask where you should comment. I asked for an objective definition of what over-commenting would be.
      - evil-olive 7y ago
        > I asked for an objective definition of what over-commenting would be. I don't think what you're asking for is possible. It's an inherently subjective standard. If an objective definition were possible, then it'd be possible to write a static analysis tool that reads both your code and the comments and flags "over-commenting on line 23, under-commenting on line 457". That could be done with sufficiently advanced AI, but at that point it would just be the subjective opinion of the tool's author being enforced.
      - replyguy912 7y ago
        over-commenting is explaining in pseudo-english what you've written in code. Prentend you are at the United Nations but you speak all the langauges, so you don't need a word-for-word translation. You don't understand to motivations of every speaker though, nor their cultural influences and a million other factors, so context is super important. In the briefings you get some of the information is not new; but if the vast majority of what you're told is obvious or discernable from what people say, you're looking at over commenting. It's not a yes-no thing but a balance of evidence, subjective opinion.
  - _ZeD_ 7y ago
    (not OP, but here's my 2c) comments should explain why you choose to write the corresponding line of code. It's a "meta-communication" between the original author (even a previous-month you) and the reader. Code reading should be "boring". The code lines (and so the meaning) should be obvious. A good comment, IMHO, should convey the information "I'm sorry for this complexity here, but you need to take care of this edge case..."
    - tchaffee 7y ago
      That's a reasonable attempt at defining what over-commenting is by trying to define what it isn't. However, it's not a very subjective definition. I tend to write fairly long comments anywhere I think it might help me in the future. I can't predict what I'll forget. I can't predict what will help me understand my code in the future. I have almost never looked at a comment and wished that someone would have written less (aside from comments that just mimic the code, e.g. "increment x"). It's almost always the opposite. I almost always wish I (or the other dev) had left more information. Literate programming comes to mind as an extreme counter example of not enough comments. https://en.wikipedia.org/wiki/Donald_Knuth#Literate_programming https://en.wikipedia.org/wiki/Donald_Knuth#Literate_programm...
      - deleted 7y ago
        [deleted]
  - throwaway35784 7y ago
    //increment i in for loop For (i=0;i++.... Var x; //define variable x X=4; //give value of 4 to x Everyone knows what that code does. The comments aren't necessary.
    - tchaffee 7y ago
      That's a good concrete example of bad comments. I suppose you could throw that in the "over-commenting" category.
      - throwaway35784 7y ago
        And, strangely, it's the only response to the gp's request to define of over-commenting, yet it is downvoted to below definitions of good commenting. So. Weird. The other responses didn't properly implement the requirement specification. I am so confused.
    - loopz 7y ago
      This is instructive to new coders, on how NOT to comment.
      - throwaway35784 7y ago
        That's what was asked for! Why on earth is the comment that properly delivers the expectation being discussed as though it's wrong?
        loopz 7y ago
        I noticed the downvote and upvoted, plus acknowledged the anti-pattern. Sometimes intent is lost in text.
    - lostgame 7y ago
      This is what I’m saying by over-commenting. I stated comments at the beginning of functions - what are the arguments? - what does it return - or at the beginning of class names are the wise go.
  - itronitron 7y ago
    I've seen code in which the development team added a revision comment in the source file for every revision to the source file, instead of just letting the version control system handle it.
  - BurningFrog 7y ago
    Some of it is an art, and thereby subjective opinion. Nothing wrong with that!
  - deckard1 7y ago
    JSDoc. It's a fucking tragedy on code bases. I've seen it happen many times now. A nice, clean, easy-to-read code base turns into a forest of unreadable shit thanks to the introduction of parsed comment tags. Perl, Ruby, Python, JS. Doesn't matter what tool or language. Please, people. I beg you. Stop putting this shit in code. Not everyone is using the same bloated IDE as you, nor do we care to maintain your silly block text and parameter text that is outdated the day you wrote it. If your function needs a block text to explain how to use it, you need to find a new job. I'm serious. You're not good at your job. If it's not self-evident what the file you're looking at does and the function within the file does, then refactor it. Cut it down. Make it make sense.
- sys_64738 7y ago
  Comment the why, not the what.
  - pytester 7y ago
    It's good to comment the what too if it's hard to discern what it's doing from the code. There have been a number of cases where, for instance, I had to call a bizarrely named API and do something unexpected in order to get an unintuitive outcome and in that case a "what" comment isn't such a bad idea.
    - tln 7y ago
      Comment the intentions and motivations for behavior.
- dplgk 7y ago
  Yes, please comment! I was once on a project where commenting was prohibited presumbely because your code should be self explanatory? Give me a break.
  - pytester 7y ago
    Comments are often a code smell indicating that the code was written in a hard to understand way. On a top notch code base - the kind that almost nobody works on - they probably should be sparse and mostly unnecessary. Moreover, when a lot of people are asked to comment they write stuff like "this function does x to y" when the function is named "x_to_y". No shit sherlock comments I call them. I'd always prefer to have good comments, but I've worked on a lot of code bases where no comments wouldn't really have been any worse.
    - tln 7y ago
      Check out the CPython code base sometime, as an example of a top notch code base. Are the comments sparse?
      - pytester 7y ago
        Depends on the area of the code you look at, but they can be fairly sparse, yes: https://github.com/python/cpython/blob/master/PC/python_uwp.cpp https://github.com/python/cpython/blob/master/PC/python_uwp.... I'd say that redis is probably a better example of gold standard clean C code, though, and they follow the rule of "don't comment unless it's decidedly non-obvious" pretty assiduously: https://github.com/antirez/redis/blob/unstable/src/ae_epoll.c https://github.com/antirez/redis/blob/unstable/src/ae_epoll....
        tln 7y ago
        Those two files do have a low ratio of comments. However a large number of files in those code bases have quite a lot more comments... I personally don't think these two code bases have sparse comments, overall, although perhaps it's subjective or my bias is affecting my judgement :) Eg, to me this is well-commented and I wouldn't call it sparse. https://github.com/antirez/redis/blob/unstable/src/latency.c https://github.com/antirez/redis/blob/unstable/src/latency.c
- kyberias 7y ago
  If you can't give clear advice on commenting, please don't give such advice.
- iLemming 7y ago
  Write a docstring for a function before you write the body of that function. Keep it short. Don't overthink it. At this point, it doesn't even have to be syntactically correct. If, in a brief sentence, written in plain English (or any other language of your choice), you can't explain the idea, you need to "go back to the drawing board." Resist the urge writing it in a programming language before you can explain it in English. When you're done writing the function, go back to the docstring, revise it; in some cases, you can even remove it. The purpose of a docstring is to help humans to quickly scan the code and discern the meaning, the idea of the function without having to read its source. Like a trailer for a movie - it should give you the general idea, but not give away the implementation details. Think about docstrings as "type annotations" for humans. We use types and type hints "to help the compiler understand our code better" because computers do not understand plain English, but very often, we have no empathy for fellow programmers.
hinkley 7y ago
Complexity is combinatorial. If you compose your code of overly complex components the end result will have much more emergent behavior. If everything at the bottom is straightforward, then people will spot more overarching concerns, instead of bogging down in minor details. I’d really love to see some cognitive science applied directly to UX and code quality concepts. Surely some of the things we espouse but don’t enforce are spot on, and others are cargo culting. Refining that list might make it harder to ignore.
taberiand 7y ago
My feeling is these paradigms, SOLID and SIMPLE, boil down to basically: small objects, connected minimally, though interfaces. SIMPLE appears to be leaning even more towards the functional programming side of things; I think we should probably just get it over with and accept that composition of functions operating on immutable data structures is just the right way to go.
- tobr 7y ago
  Is there a language that leans heavily towards immutable data, but steers clear of the, shall we say, dorkier side of functional programming?
  - 7thaccount 7y ago
    Julia is pretty good at this. Immutability is the default with functional composition. It is primarily intended for numerics though.
  - xenihn 7y ago
    Swift.
  - ummonk 7y ago
    JS with React is great if you use an immutable data structures library and compose functions.
    - deckard1 7y ago
      ES6 and newer JS is a great functional language. That said, I do not recommend immutable libraries. Here are the reasons: 1. They provide false comfort. Nothing in JS is truly immutable. People are just going to end up breaking the rules (purposely or inadvertently). 2. Boxing and unboxing regular JS objects becomes a pain in the ass and a maintenance horror show. You'll never know what an object is and you'll have to jump through countless hoops to get plain old JS objects to do anything with anyway. Much better is to educate developers, and make sure code is properly reviewed before merging. Immutability doesn't need to be built into the language. Code customs and practices can go a long way.
thinkpad20 7y ago
> Error: ENOENT, no such file or directory '~/foorc' I can’t count how many times I’ve seen error messages that look like this, often with no context at all, in JavaScript apps, even widely used ones like npm and webpack. Proper error handling is never easy, but the JS community seems particularly given to avoiding it.
dplgk 7y ago
But wait, I want all my code to work in linear space and time, look like assembly code and scale to 4 billion servers.
- dang 7y ago
  Please don't post unsubstantive comments here.
avmich 7y ago
"Keep the story going. Sign up for an extra free read. You've completed your member preview for this month, but when you sign up for a free Medium account, you get one more story." Sorry, can't read behind paywall.
- kevingoslar 7y ago
  Agreed, sorry for the paywall. Is there a better place to post such stories than Medium?
orenkt 7y ago
can author of that medium post show real world example of an app, build with those principles and rules from start to end? it would be also very educational to see decision and design process of an app build with those rules.

71 points by kevingoslar 7y ago

lostgame 7y ago

I couldn’t agree more. Also; keep it clean. Don’t over-comment, but comment.

tchaffee 7y ago
Can you define "over-comment"? Without a clear definition, it's just subjective opinion.
- lostgame 7y ago
  Sure! The beginnings of functions, for instance, are great places to comment, perhaps even including a definition of some of the subroutines within it. In the case of an exceptionally large subroutine, commenting within the subroutine may be advantageous - but at that point you may consider another function to replace that larger chunk. Variable names that are perhaps obscure and are not practical to rename for whatever reason can also use comments. Class headers are of course also a great place to comment, to explain the purpose of the class. Good comments can lead to better code. :)
  - tchaffee 7y ago
    You didn't really answer my question though. I didn't ask where you should comment. I asked for an objective definition of what over-commenting would be.
    - evil-olive 7y ago
      > I asked for an objective definition of what over-commenting would be. I don't think what you're asking for is possible. It's an inherently subjective standard. If an objective definition were possible, then it'd be possible to write a static analysis tool that reads both your code and the comments and flags "over-commenting on line 23, under-commenting on line 457". That could be done with sufficiently advanced AI, but at that point it would just be the subjective opinion of the tool's author being enforced.
    - replyguy912 7y ago
      over-commenting is explaining in pseudo-english what you've written in code. Prentend you are at the United Nations but you speak all the langauges, so you don't need a word-for-word translation. You don't understand to motivations of every speaker though, nor their cultural influences and a million other factors, so context is super important. In the briefings you get some of the information is not new; but if the vast majority of what you're told is obvious or discernable from what people say, you're looking at over commenting. It's not a yes-no thing but a balance of evidence, subjective opinion.
- _ZeD_ 7y ago
  (not OP, but here's my 2c) comments should explain why you choose to write the corresponding line of code. It's a "meta-communication" between the original author (even a previous-month you) and the reader. Code reading should be "boring". The code lines (and so the meaning) should be obvious. A good comment, IMHO, should convey the information "I'm sorry for this complexity here, but you need to take care of this edge case..."
  - tchaffee 7y ago
    That's a reasonable attempt at defining what over-commenting is by trying to define what it isn't. However, it's not a very subjective definition. I tend to write fairly long comments anywhere I think it might help me in the future. I can't predict what I'll forget. I can't predict what will help me understand my code in the future. I have almost never looked at a comment and wished that someone would have written less (aside from comments that just mimic the code, e.g. "increment x"). It's almost always the opposite. I almost always wish I (or the other dev) had left more information. Literate programming comes to mind as an extreme counter example of not enough comments. https://en.wikipedia.org/wiki/Donald_Knuth#Literate_programming https://en.wikipedia.org/wiki/Donald_Knuth#Literate_programm...
    - deleted 7y ago
      [deleted]
- throwaway35784 7y ago
  //increment i in for loop For (i=0;i++.... Var x; //define variable x X=4; //give value of 4 to x Everyone knows what that code does. The comments aren't necessary.
  - tchaffee 7y ago
    That's a good concrete example of bad comments. I suppose you could throw that in the "over-commenting" category.
    - throwaway35784 7y ago
      And, strangely, it's the only response to the gp's request to define of over-commenting, yet it is downvoted to below definitions of good commenting. So. Weird. The other responses didn't properly implement the requirement specification. I am so confused.
  - loopz 7y ago
    This is instructive to new coders, on how NOT to comment.
    - throwaway35784 7y ago
      That's what was asked for! Why on earth is the comment that properly delivers the expectation being discussed as though it's wrong?
      - loopz 7y ago
        I noticed the downvote and upvoted, plus acknowledged the anti-pattern. Sometimes intent is lost in text.
  - lostgame 7y ago
    This is what I’m saying by over-commenting. I stated comments at the beginning of functions - what are the arguments? - what does it return - or at the beginning of class names are the wise go.
- itronitron 7y ago
  I've seen code in which the development team added a revision comment in the source file for every revision to the source file, instead of just letting the version control system handle it.
- BurningFrog 7y ago
  Some of it is an art, and thereby subjective opinion. Nothing wrong with that!
- deckard1 7y ago
  JSDoc. It's a fucking tragedy on code bases. I've seen it happen many times now. A nice, clean, easy-to-read code base turns into a forest of unreadable shit thanks to the introduction of parsed comment tags. Perl, Ruby, Python, JS. Doesn't matter what tool or language. Please, people. I beg you. Stop putting this shit in code. Not everyone is using the same bloated IDE as you, nor do we care to maintain your silly block text and parameter text that is outdated the day you wrote it. If your function needs a block text to explain how to use it, you need to find a new job. I'm serious. You're not good at your job. If it's not self-evident what the file you're looking at does and the function within the file does, then refactor it. Cut it down. Make it make sense.
sys_64738 7y ago
Comment the why, not the what.
- pytester 7y ago
  It's good to comment the what too if it's hard to discern what it's doing from the code. There have been a number of cases where, for instance, I had to call a bizarrely named API and do something unexpected in order to get an unintuitive outcome and in that case a "what" comment isn't such a bad idea.
  - tln 7y ago
    Comment the intentions and motivations for behavior.
dplgk 7y ago
Yes, please comment! I was once on a project where commenting was prohibited presumbely because your code should be self explanatory? Give me a break.
- pytester 7y ago
  Comments are often a code smell indicating that the code was written in a hard to understand way. On a top notch code base - the kind that almost nobody works on - they probably should be sparse and mostly unnecessary. Moreover, when a lot of people are asked to comment they write stuff like "this function does x to y" when the function is named "x_to_y". No shit sherlock comments I call them. I'd always prefer to have good comments, but I've worked on a lot of code bases where no comments wouldn't really have been any worse.
  - tln 7y ago
    Check out the CPython code base sometime, as an example of a top notch code base. Are the comments sparse?
    - pytester 7y ago
      Depends on the area of the code you look at, but they can be fairly sparse, yes: https://github.com/python/cpython/blob/master/PC/python_uwp.cpp https://github.com/python/cpython/blob/master/PC/python_uwp.... I'd say that redis is probably a better example of gold standard clean C code, though, and they follow the rule of "don't comment unless it's decidedly non-obvious" pretty assiduously: https://github.com/antirez/redis/blob/unstable/src/ae_epoll.c https://github.com/antirez/redis/blob/unstable/src/ae_epoll....
      - tln 7y ago
        Those two files do have a low ratio of comments. However a large number of files in those code bases have quite a lot more comments... I personally don't think these two code bases have sparse comments, overall, although perhaps it's subjective or my bias is affecting my judgement :) Eg, to me this is well-commented and I wouldn't call it sparse. https://github.com/antirez/redis/blob/unstable/src/latency.c https://github.com/antirez/redis/blob/unstable/src/latency.c
kyberias 7y ago
If you can't give clear advice on commenting, please don't give such advice.
iLemming 7y ago
Write a docstring for a function before you write the body of that function. Keep it short. Don't overthink it. At this point, it doesn't even have to be syntactically correct. If, in a brief sentence, written in plain English (or any other language of your choice), you can't explain the idea, you need to "go back to the drawing board." Resist the urge writing it in a programming language before you can explain it in English. When you're done writing the function, go back to the docstring, revise it; in some cases, you can even remove it. The purpose of a docstring is to help humans to quickly scan the code and discern the meaning, the idea of the function without having to read its source. Like a trailer for a movie - it should give you the general idea, but not give away the implementation details. Think about docstrings as "type annotations" for humans. We use types and type hints "to help the compiler understand our code better" because computers do not understand plain English, but very often, we have no empathy for fellow programmers.

hinkley 7y ago

Complexity is combinatorial. If you compose your code of overly complex components the end result will have much more emergent behavior. If everything at the bottom is straightforward, then people will spot more overarching concerns, instead of bogging down in minor details. I’d really love to see some cognitive science applied directly to UX and code quality concepts. Surely some of the things we espouse but don’t enforce are spot on, and others are cargo culting. Refining that list might make it harder to ignore.

taberiand 7y ago

My feeling is these paradigms, SOLID and SIMPLE, boil down to basically: small objects, connected minimally, though interfaces. SIMPLE appears to be leaning even more towards the functional programming side of things; I think we should probably just get it over with and accept that composition of functions operating on immutable data structures is just the right way to go.

tobr 7y ago
Is there a language that leans heavily towards immutable data, but steers clear of the, shall we say, dorkier side of functional programming?
- 7thaccount 7y ago
  Julia is pretty good at this. Immutability is the default with functional composition. It is primarily intended for numerics though.
- xenihn 7y ago
  Swift.
- ummonk 7y ago
  JS with React is great if you use an immutable data structures library and compose functions.
  - deckard1 7y ago
    ES6 and newer JS is a great functional language. That said, I do not recommend immutable libraries. Here are the reasons: 1. They provide false comfort. Nothing in JS is truly immutable. People are just going to end up breaking the rules (purposely or inadvertently). 2. Boxing and unboxing regular JS objects becomes a pain in the ass and a maintenance horror show. You'll never know what an object is and you'll have to jump through countless hoops to get plain old JS objects to do anything with anyway. Much better is to educate developers, and make sure code is properly reviewed before merging. Immutability doesn't need to be built into the language. Code customs and practices can go a long way.

thinkpad20 7y ago

> Error: ENOENT, no such file or directory '~/foorc' I can’t count how many times I’ve seen error messages that look like this, often with no context at all, in JavaScript apps, even widely used ones like npm and webpack. Proper error handling is never easy, but the JS community seems particularly given to avoiding it.

dplgk 7y ago

But wait, I want all my code to work in linear space and time, look like assembly code and scale to 4 billion servers.

dang 7y ago
Please don't post unsubstantive comments here.

avmich 7y ago

"Keep the story going. Sign up for an extra free read. You've completed your member preview for this month, but when you sign up for a free Medium account, you get one more story." Sorry, can't read behind paywall.

kevingoslar 7y ago
Agreed, sorry for the paywall. Is there a better place to post such stories than Medium?

orenkt 7y ago

can author of that medium post show real world example of an app, build with those principles and rules from start to end? it would be also very educational to see decision and design process of an app build with those rules.