• magic_lobster_party@kbin.social
    link
    fedilink
    arrow-up
    2
    arrow-down
    1
    ·
    1 year ago

    No. Just give the function a good descriptive name with good descriptive parameters. Keep the function simple too. If you can’t, try to refactor and see if that helps.

    If you are still unable to express yourself via code, then you should use comments to guide the reader.

    • auchschonda@feddit.de
      link
      fedilink
      arrow-up
      2
      ·
      edit-2
      1 year ago

      What about exceptions raised within the function? Will you also put them in the descriptive function name? ;)

          • magic_lobster_party@kbin.social
            link
            fedilink
            arrow-up
            1
            ·
            1 year ago

            According to who? If I have access to the source code, which I often do, I’d rather just read the code. Chances are that if documentation exists, it’s no longer up to date.

            • auchschonda@feddit.de
              link
              fedilink
              arrow-up
              2
              ·
              1 year ago

              Modularity. Part of it is defining a proper Interface for using the hidden complexity.

              Exceptions are only one example. Functions can have behavior, inner states, prior calling requirements etc… you cannot read from its mere prototype.

              Do you really want everyone to read the inner code to learn that?

              Chances are that if documentation exists, it’s no longer up to date.

              This risk also applies to descriptive function names. They can be poor, wrong or outdated, too.