12

I hate to write clutter comments! Honestly, comment every method is fucking stupid.

If I have a method that is called "getCalendar" that takes as parameter "timestamp: Timestamp" and returns "Calendar", then I don't need to write:

/**
* Create a calendar from the given timestamp
* @param timestamp Timestamp from which the calendar is created
* @return Calendar Calendar returned
*/

I understand why we do that in older PHP versions, in which we need that for IDE support.

I understand why we do that if the javadocs are automatically created.

But that's not the case here. It's just a coding convention and all it does is make me not read comments anymore. Because they are everywhere. The code is often shorter. And I chose the name getCalendar because it already describes perfectly what it does.

There is a time and place for a comment. Something like this:

def getCalendar(timestamp: Timestamp = Timestamp("2018-03-14 00:00:00")): Calendar

Here I'd like to read a comment like:
Defaults to 2018-03-14 because that is the founding day of the company. No timestamp can ever be earlier until we have invented time machines and in that case stop me from writing this comment.

Okay, being serious, a default date that like that warrants a comment. Comments have their place. But when you put them everywhere, I stop reading them. And you just devalued important comments by cluttering everything redundantly.

Oh, and guess what happens when you change what this method does... You will forget to update the comment.

Fuck clutter comments.

Comments
  • 3
    I agree with you that commenting everywhere is just stupid. Usually you can refactor the code if you need to add a comment.

    I only comment when I want to describe the weird magic/hack I have done , to add a guard against strange bug which occur or when I wanted to add a funny joke.

    In other note I always comment my class since it is not easy to choose a short class name with information to find out what it does. For example take a class name "Time".
  • 1
    Yeah a one off thing, no need to comment much.

    Something a little weird or has something not obvious, comment away.
  • 4
    Solution: don't write comments, but self-explanatory code :)
  • 2
    @vintprox Or don't write code, but self-executing comments.
  • 2
    @Fast-Nop

    We are living in the future when we get write self-executing comment.
  • 3
    Except that was a bad example. If the function accepts a parameter named timestamp; Does it return a calendar from now to timestamp? Does it return a calendar ending one month after the timestamp? Does it return a calendar starting one month before the timestamp? Does it return a calendar for the current year/week/month of the timestamp?

    So many questions :|
  • 2
    What's the format for timestamp. In our REST API there's no standard for passing in a date.

    Some people used yyyyMMdd, other created methods expecting yyyy-mm-dd and some others needed ISODATE....

    So in the API Docs method descriptions, a few years ago I said... For any date param, include the format expected...

    Comments arent for you, it's for whoever needs to reuse ur code. Or the future you 1yr from now.

    We have a lot of code duplication too cuz no one refactors or comments on what their methods do. And a lot of methods are huge so without comments it takes rocket science and a lot of time even if I wanted to refactor to reuse parts of it. Cuz u need to understand the whole thing....

    And well uncommented code usually looks like monkey shit to a diff dev
  • 1
    @billgates Public facing api. Sure, yeah, add it to my list of valid documentation reasons.

    But long method? Nope. Don't write long methods. Don't get me wrong, I am under time pressure, too. Sometimes we write ugly code. And sometimes all the time budget allows is add a comment explaining what something does. But generally, do not write code that needs commenting.

    I hate it when there are hundreds of lines of code. Complete mixture of different levels of abstraction. Just break it up in smaller functions that just do one thing.

    But if you do that, you might end up with many functions. So a functions is on average 3 lines. A comment is on average 5 lines.

    Heck, many of my functions are one liners. Scala for the win. Something like this:

    private def getUser(userId: Long): Future[UserResponse] = dispatcher.getUser(userId)

    The comment would look like this:

    /**
    * Get a user
    * @param userId id of the user
    * @return
    */
  • 1
    @TheCommoner282 I may write longer methods but I think my avg would be 10 lines though I'm Java not Scala. The problem comes when I need to hand it off to someone else. I may know what it is because I have the business context, emails, requirements but to some guy that doesn't have that, and needs to reverse engineer the Why? Comments help.

    I do a lot of reverse engineering before and without the business reason/rationale clearly stated, it takes a lot of reverse engineering and time... Usually until I finish going over the whole code base that I can get a bit of sense of what it's supposed to do and why.

    And I think most IT devs can't do that or have enough time too.

    And when I'm coding sometimes I can't think of a nice perfect name for a method.

    But in the first pass, when I create those big methods, sometimes I'm just not really sure how to split it out... Until later on, when things are a bit more stable or when adding some new code and thinking "this logic I'm going to write now feels familiar.... Where have I seen this before" and then I go back look for the old function and see which part can be broken out and reused.
  • 1
    Create a calendar from a timestamp? But in my book, calendars aren't bound to any specific timestamp. What's the purpose of the timestamp then? How do you use it? That should be commented.
  • 0
    @Lor-inc How would a calendar work without a given time? You tell them a time and then calendar can tell you what day of the week it is or what day of the week it would be if you added another year on top of that day. But it always needs a date time information first. Calendar don't just produce all dates from 1980-2038.
  • 1
    @TheCommoner282 My calendar is a book with slots for each day allowing me to write events, and I'd call what you're talking about a CalendarQuery or just a Date.
    This goes to show that nothing is obvious and this class deserves a comment along the lines of "provides information like month or day-of-week on the given timestamp".
  • 0
    @Lor-inc that class is a java standard. If you are having a half way decent IDE, it shows you what it does. Commenting it would at best add redundancy.

    And if I comment a class, the comment will be on the class, not on a provider or factory
  • 1
    @TheCommoner282 Apologies, I didn't know this was in STL.
  • 0
    Yes clutter comments are bad, but what if you need to document your code for example? I personally use doxygen for somewhat automating it and then each function requires at least a very basic description...
  • 0
    @NEMESISprj that sounds like you're having lots of clutter. Or not enough functions.
Add Comment