• Michael R (unregistered)

    public function setComment($frist) { $this->comment = $frist; return $this; }

  • Quite (unregistered)

    Reminds me of a project we developed for a client to whom we had sold access to the API of our product. I had been posted to the client's location (in the middle of winter, on a different continent, one which did not enjoy the benefits of the Gulf Stream, some 10 km from the hotel, no company car issued, I had to use public transport, which resulted in me standing each evening at a bus stop for up to half an hour,often in a fairly cold blizzard) for a few months.

    Reasonably enough, we were asked to provide the full javadocs of the API. So I dutifully sent this request to the office back home. It took an age for them to respond to this. When I did, I was greeted with method headers along the lines of:

    "I suppose we really ought to fill these in, you never know when a client is going to require them."

    I was not overly upset to be dismissed from that posting by the client, who decided that our company was not the perfect fit for them. I do still miss the poutine and the jazz clubs, though.

  • Industrial Automation Engineer (unregistered)

    value is null.

  • Tim (unregistered)

    Generally I only put comments in the code where the reader couldn't reasonably understand what is going on without them. Often this is explaining why it's doing what it does, which is the thing most often missing from comments in my experience.

  • Lothar (unregistered)

    The comments look auto-generated, so it's no wonder why they don't tell you more about some metho than some hard-wired-algorithm is capable of guessing.

    I'm sure with there will be some AI in the future that will help you creating better documentation... or at least something that some maketing-droid will sell you as such.

  • WTFGuy (unregistered)

    @Tim nailed it. It's also useful to document the "Why would a caller use this?" IOW, the use case(s) it's meant to solve.

    As to the return $Self fluency, once one is used to working with fluent APIs, seeing "Returns self/this" in the pop-up Intellisense or whatever your IDE calls it amount to a very & concise clear signal: "I'm a fluent method". Probably of more use than some sentence buried in the rest of the method's remarks commentary.

    Having said that, adopting fluent style must be a project- or API-level decision, not a method-by-method or worse, dev-by-dev, decision. Either on the design-of-API end or on the user-of-the-API end.

    @Quite: I had a similar posting once. Downtown Montreal for one week each month for about 18 months. July was heavenly. February was ... not. Unsurprisingly, my 18 months there comprised two winters and one summer, not the converse.

  • Heinebold (unregistered)

    In php versions before they added actual typing, this was what you did to add the type information to get IDE support.

    TRWTF is old php not having that, but the use of the doc conventions (including "self" -> that references the Type of the object, $this is the instance) here is completely correct and not a WTF.

  • (nodebb)

    TBH we're using PHP with fluent APIs quite comfortably. They're not EVERYWHERE - but they are quite useful for certain things like entities where you can just go

    $x = (new MyEntity)
    ->setFieldA($a)
    ->setFieldB($b)
    ->setFieldC($c)
    ->save();

    This is actually pretty readable and IntelliSense helps with writing this. Also there are some places where an operation can take up to 30 different parameters from which you typically only use 5 - so that's a nice fit for fluent APIs too:

     (new Operation())
    ->setParamA($a)
    ->setParamB($b)
    ->setPAramC($c)
    ->execute();
  • Barry Margolin (github)

    A coding standard that requires every function to be documented is not unreasonable, while simple functions like these can't really be described much better than repeating the function name with spaces.

  • (nodebb)

    jsdoc comments with type information being useful only works if the type information is accurate. Better to use TypeScript since the transpiler enforces type restrictions so you get errors when there is a problem with the types.

  • code refactorer (unregistered)

    Some time ago, my old company bought software written with BroadVision portal and we were struggling with single methods that returned error numbers and at the same time also threw exceptions. But the worst thing was the missing documentation. All methods had autogenerated javadocs. One method for example was called "setDate(int theYear, int theMonth, int theDay, int theInt)". And the description was: "method: setDate, parameters: theYear the year, theMonth the month, theDay the day, theInt the int". We spent a lot of time figuring out if the year was 2 or 4 digits and if the month was zero-based or one-based. But we never could figure out what purpose "theInt" was for and what values you could pass.

  • Michael R (unregistered) in reply to code refactorer

    Holy moly. I had to endure Boredvision in the early 2000s. I can relate.

  • Tim Ward (unregistered)

    I prefer comments that mean I don't have to read the code.

    The comment at the top of a file should be sufficient to tell me whether or not I care about this file, same for classes and methods.

  • Jewellery (unregistered)
    Comment held for moderation.
  • MaxiTB (unregistered)

    I am confused, I worked with fluent APIs long before they were called like that and "return self" was always a good indicator. It goes way back to the 70s and 80s. So for a senior dev like me it's odd that younger people (?) can not understand what pattern or principles apply with a simple two word implementation. I guess that is what you get with nowadays LEGO approach of teaching development and no really teaching what goes into those LEGOs?

  • Sole Purpose Of Visit (unregistered)

    Just to be a contrarian ...

    I don't see anything wrong with this approach. The whole point about XML (or equivalent) documentation is that it is, er, documentation. You can run it through a text parser and create actual, you know, documentation. Obviously there will be a round trip involved, but that's a simple build process.

    I would far rather have a basic word/rtf/whatever document that describes an interface than, y'know, not have anything at all apart from thousands of lines of code I need to read through with no guidance at all. But then, I am old school.

Leave a comment on “Doc Block”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article