Recently, I’ve been thinking about few common anti-patterns I tend to see in professional JavaScript projects. Today, I wanted to talk about one of them: no docs. A lot of more seasoned developers have this obsessed with “self-documenting code.” And its true that if you write functions that do just one thing and follow logical naming conventions, what a piece of code does can often be pretty apparent. Looking at the addItemToCart() function below, I can pretty quickly determine that I pass in the ID of the item to add, and it updates the quantity of that item in the cart object.
  • relevants@feddit.de
    31·
    10 months ago

    I’m a bit split on this. I do think in general all functions and methods should have comments describing how they behave, but I also think the standard format of Javadoc or JSDoc can look a bit redundant and silly sometimes, at least wrt getters and setters. I often see things like

    /**
 * Get the customer ID.
 *
 * @return the ID of the customer
 */
public getId(): string {
    // ...
}

    Now sure, you could argue that this is more of a problem with the Java-esque way of abstracting away field access than with the documentation, but sometimes there just genuinely isn’t anything meaningful to add that isn’t already expressed by the method name and signature. In that case, these comments add visual noise to the class and no real value. As soon as there is more logic to it than that though, I completely agree that should be documented for any caller.

    I’m not sure I like it better, but I do find Kotlin’s approach to this quite interesting, where parameters and return values are referenced from the description text rather than always listed separately.

    • shnizmuffinAEnglish
      2·
      10 months ago

      In your example, without the comment, I’d have no way of knowing it was a customer ID I’m getting, unless the only objects with IDs are customers.

      • relevants@feddit.de
        11·
        10 months ago

        I mean, the example kinda implies that this is on a Customer type. Otherwise you’d have a method getCustomerId instead.