• @towerful
    link
    1510 months ago

    Self documenting code is more about using sensible names and explicit code.
    So addItemToCartByProductId instead of updateCart.
    The idea being, once you get the hang of an API, you can pretty much just guess what the name of the thing you want.
    And this applies at all levels.
    So cart[id] might be better as cart[productId] because id is ambiguous. Is it the id of the cart? Is that keyed by some user session?
    Suddenly you are having to maintain a larger scope in your mental model to try and understand what’s going on.
    You could argue the cart variable could be named better. Or perhaps it’s an internal variable, and it gets wrapped in accessor/mutator methods or whatever.

    It’s the names and syntax that should tell you what things do.
    Comments should tell you why complex or obtuse things are being done.

    However, code used by multiple people (eg libraries, APIs, open source projects, group/company projects) absolutely need the meta-docunentation. The JSDocs, the readmes, examples, install, config, API overview and all that.

    Wikipedia has a good entry on it.
    https://en.m.wikipedia.org/wiki/Self-documenting_code
    Notably the “objectives” part:

    Reduce the need for users and developers of a system to consult secondary documentation sources such as code comments or software manuals[2]

    Reduce, not remove.
    So the documentation still needs to exist.

  • @[email protected]
    link
    fedilink
    210 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.

    • shnizmuffin
      link
      fedilink
      English
      210 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.

      • @[email protected]
        link
        fedilink
        010 months ago

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

  • Codex
    link
    fedilink
    110 months ago

    All style guides are poop if they don’t start by setting a context for when the guidelines are to be used. If you are the only developer on a project then spending a lot of time setting up protected access to hidden variables and documenting every function as though this was a public API is a waste of time.

    Trust me, just put it all in one big file and use good names for things. Then you can see all the code, know what it does, and easily fix that weird bug that cropped up two years later because of browser updates.

    Now if you’re on an actual TEAM of people, that’s very different. Use dependency injection, use high-level (MVP, MVC, MVVM, etc) patterns to organize things, and especially use the documentation comments to describe WHY things work in a certain way. Use good naming and organization to state WHAT things are. “getID” is a terrible function name, but “customer.getID” is an alright method name. “Gets the ID of a customer” is a waste of everyone’s time as documentation, but “Calculates the ID using a hash of customerRecordID and customerSessionID” is a really important comment that will help someone solve a very irritating bug someday.

    All these tools like doc comments, readonly access to protected internal state, and all the SOLID principles exist to ease Programming-in-the-Large. That is they help teams of people working on big projects that span hundreds of files. Breaking out all this stuff for solodev applications that have less than 10K lines of actual code is complexity for it’s own sake and ends up making simple applications far less readable and maintainable.