13

*Pro tip:* add comments in your code stating what you're gonna write next! This helps the reader to know what to expect!

[filename EventsTable.js]

Comments
  • 5
    I think this happens when the template gets too big and devs feel the urge to "document" it...
    Splitting the trmplate into smaller components helps.
  • 2
    @PonySlaystation that's totally the point I guess, I mean, that's why we use ReactJS right?
  • 2
    amazing they even use js comments...

    what is wrong with html comments ?

    Is it generated ?
  • 4
    Common noob mistake. They get told: Write comments and aren't bold enough to ask, "why?" So they write the typical compliance comments...

    Tell and show em when and why comments are to be written.
  • 6
    @Oktokolo That’s an understatement. 90% of all the comments in the world are exactly this.
  • 2
    to comment properly in html, use:

    <!-- comment text -->
  • 4
    @thebiochemic @Grumm html comments appear in the end result, these comments are for source code only
  • 5
    @alexbrooklyn My bad. Should have seen the react tag and how confused that one is.

    I am more familiar with Nuxt and vue... where you know, html is plain html. Not some crazy return call :D
  • 1
    @alexbrooklyn isn't that the reason why you have minifiers and shit in your pipeline?

    It would be really stupid to dictate commenting behaviour based on what the end result would be.
  • 0
    @thebiochemic Well ultimately it's still javascript
  • 9
    > Pic related
  • 5
    Kinda wish the class comic in the post above me had a sequel showing examples of a GOOD codebase.

    Cause I've heard a dev get the wrong idea after reading it

    "Where could this bridge possibly lead?" and "Why is this structure here?" can be interpreted as if comments should mention where a class/struct/component will be used in the codebase.

    Like "class Bridge //used to connect Land classes to each other" or "struct WallWithLadder //used as part of class House"

    (Which would be bad comments! As they'll rot and start to lie as the code changes)
  • 2
    @jiraTicket It is hard to find real life examples which aren't code.

    Good real life "comments" but totally misleading when used to explain good use in code are most signs with shop opening hours, safety markings and some street sign attachments telling the drivers why some sign is there.
  • 2
    @Oktokolo True but my idea was that the examples themselves should not matter (perhaps it's even a benefit to have the examples be non-intuitive to simulate the experience of reading an unfamiliar codebase for the first time)

    The focus should be entirely on the way they code comments are written.

    To show that a good code comment would NOT say "this Bridge is used in Class Y" but rather something along the lines of why it was built and why it's weird (maybe a business requirement)

    Like: when you come across a Bridge what kinda comment would help
  • 1
    @jiraTicket @Oktokolo maybe a good real life example could be something like the winding "inefficient road" but with a nice, straight road next to it and a sign, "hidden quicksand on the straight road! Twisty is safe"

    Or something along those lines... You guys are right, it's difficult.
Add Comment