1. 15
  1.  

  2. 4

    Most of this is applicable to any language, so well worth the read. Few important points:

    • Your API will outlast your implementation, so the API is more important.

    • Boolean parameters are the devil, don’t do it!

    1. 2

      i’m struggling to find the part about boolean parameters. where is it?

      i am interested because i am working on an api at the moment, for CRC (checksums) and they are described by a couple of boolean flags - whether the bytes are inverted before and/or after calculation. it seems to me that if i don’t have boolean parameters i’d need a set of verbosely named functions that wouldn’t be any clearer to the user than one with booleans.

      1. 5

        i’d swap booleans for something more typed. an enum instead of verbosely named function is a nice between ground. then hopefully, you have a type system that can check that the enums are of the correct type.

        its pretty easy with multiple booleans to get the ordering wrong (the same would go for something that has a signature of Int, Int or whatever)

        1. 1

          oh, good point. yes, that’s easy to do. i was thinking the implication was more that you should separate logic in different functions. thanks.

        2. 3

          In 4.1

          The meaning of the arguments to a method should be clear from the context at the call site. Beware of bool parameters, which often lead to unreadable code.

        3. 1

          Really wish the browser and DOM people heeded both these points more carefully.