3 ms·

1. When your comments are longer than your code, either you're putting in too many comments, or your code is too hard to read. (The former seems to be the case

1. When your comments are longer than your code, either you're putting in too many comments, or your code is too hard to read. (The former seems to be the case here.) 2. Why is the spacing convention all over the place in some files? https://github.com/m4nuC/memGame/blob/master/app/controllers/ScoresController.php#L10 https://github.com/m4nuC/memGame/blob/master/app/controllers... https://github.com/m4nuC/memGame/blob/master/app/database/migrations/2014_07_03_144443_add_high_score_table.php#L13 https://github.com/m4nuC/memGame/blob/master/app/database/mi... 3. Why are there so many folders that only have .gitignore's inside them? In fact, why are there so many folders at all? 4. In my glances at some of your files I didn't find a single function with a lot of "meat" inside it, so it doesn't show much about your ability to write something that actually does something.

jsmthrowaway 12y ago
> 1. When your comments are longer than your code, either you're putting in too many comments, or your code is too hard to read. (The former seems to be the case here.) I hate this meme. There's nothing wrong with too much commentary. You are not on a comment budget. Please stop spreading this around, like the "rewriting is always a bad idea" meme that's embedded itself in young developers like dogma even though Spolsky's point is up for debate. Atwood is wrong about this one, too, and I hate that Spolsky and Atwood have so many "rules" of programming that people pass around. I've seen this meme borne out via comment ratio rules in style guides. That's ridiculous. We all work in editors that make comments a different color. I use light gray. My eyes can look right past them, but if I want the paragraph or two explaining the algorithm I'm looking at, it's there. The underlying flaw in Atwood's claim is that it is possible to write code in a way that is self-evident to every reader. You do not know every reader. Well-written commentary -- bordering on literate programming -- makes development much better. Even better if the code is the documentation. I don't know where this notion that we must conserve comments like water came from, but I'd be happy if it just stopped. Note here that I'm addressing quantity, not quality. I feel that is important to clarify.
- wfunction 12y ago
  I think you might've misunderstood what I'm saying. It's perfectly fine to have complex functions commented as much as necessary; heck, it's totally fine to have your comments be 100x as long your function when the function is actually hard to understand. What's not OK is commenting ALL of your code, especially not to such an extent where the comments are actually longer than the code size on average. (!) Some stuff just has to be self-explanatory, period -- that's a fact, not a meme. If you can't make the simplest code self-explanatory, then I'm sorry but you simply can't code as well as someone who can. And if you're going to comment everything, then you're also wasting valuable time that someone who didn't need to do so would've spent writing actual code and getting more done.
  - jsmthrowaway 12y ago
    I understand what you are saying perfectly, but you typed "you are putting in too many comments" as a possibility, full stop. All of that context you just painted for me is not in your comment. That's how "never rewrite because rewriting is bad because reasons" gets started. And absolutely I think commenting all your code is okay. I honestly wish literate programming had caught on.
    - wfunction 12y ago
      Well, quantity can be measured in different ways. I didn't say "your (individual) comments are too long"; I said "you have too many comments" (aka the total length of your comments is comparable to the total length of your code... i.e., your source files are on average more comments than code). Too many comments (even short ones) is generally bad; they make the code harder to read, not easier. A few long comments are generally good. I feel like you were addressing a different point than I was making.
      - jsmthrowaway 12y ago
        > Too many comments (even short ones) is generally bad; That's exactly what I'm refuting, so I'm not sure why you keep talking past me. I am speaking to the crazy notion that there is a par for the comment golf course, and we all have to be Goldilocks as we write software. I don't know where that started, but I'd love it if people stopped judging software based upon the non-executable portions. A line before every line? Maybe. Are they comments of quality? I've put a comment on every line of assembly before as a postfix. There is no hard and fast rule on this, and I wish people would stop trying to make one. Again, literate programming. I feel like you're missing how serious I am about this by overlooking my repeated love for it.

jsmthrowaway 12y ago

> 1. When your comments are longer than your code, either you're putting in too many comments, or your code is too hard to read. (The former seems to be the case here.) I hate this meme. There's nothing wrong with too much commentary. You are not on a comment budget. Please stop spreading this around, like the "rewriting is always a bad idea" meme that's embedded itself in young developers like dogma even though Spolsky's point is up for debate. Atwood is wrong about this one, too, and I hate that Spolsky and Atwood have so many "rules" of programming that people pass around. I've seen this meme borne out via comment ratio rules in style guides. That's ridiculous. We all work in editors that make comments a different color. I use light gray. My eyes can look right past them, but if I want the paragraph or two explaining the algorithm I'm looking at, it's there. The underlying flaw in Atwood's claim is that it is possible to write code in a way that is self-evident to every reader. You do not know every reader. Well-written commentary -- bordering on literate programming -- makes development much better. Even better if the code is the documentation. I don't know where this notion that we must conserve comments like water came from, but I'd be happy if it just stopped. Note here that I'm addressing quantity, not quality. I feel that is important to clarify.

wfunction 12y ago
I think you might've misunderstood what I'm saying. It's perfectly fine to have complex functions commented as much as necessary; heck, it's totally fine to have your comments be 100x as long your function when the function is actually hard to understand. What's not OK is commenting ALL of your code, especially not to such an extent where the comments are actually longer than the code size on average. (!) Some stuff just has to be self-explanatory, period -- that's a fact, not a meme. If you can't make the simplest code self-explanatory, then I'm sorry but you simply can't code as well as someone who can. And if you're going to comment everything, then you're also wasting valuable time that someone who didn't need to do so would've spent writing actual code and getting more done.
- jsmthrowaway 12y ago
  I understand what you are saying perfectly, but you typed "you are putting in too many comments" as a possibility, full stop. All of that context you just painted for me is not in your comment. That's how "never rewrite because rewriting is bad because reasons" gets started. And absolutely I think commenting all your code is okay. I honestly wish literate programming had caught on.
  - wfunction 12y ago
    Well, quantity can be measured in different ways. I didn't say "your (individual) comments are too long"; I said "you have too many comments" (aka the total length of your comments is comparable to the total length of your code... i.e., your source files are on average more comments than code). Too many comments (even short ones) is generally bad; they make the code harder to read, not easier. A few long comments are generally good. I feel like you were addressing a different point than I was making.
    - jsmthrowaway 12y ago
      > Too many comments (even short ones) is generally bad; That's exactly what I'm refuting, so I'm not sure why you keep talking past me. I am speaking to the crazy notion that there is a par for the comment golf course, and we all have to be Goldilocks as we write software. I don't know where that started, but I'd love it if people stopped judging software based upon the non-executable portions. A line before every line? Maybe. Are they comments of quality? I've put a comment on every line of assembly before as a postfix. There is no hard and fast rule on this, and I wish people would stop trying to make one. Again, literate programming. I feel like you're missing how serious I am about this by overlooking my repeated love for it.