Zum Hauptinhalt springen
Chris’ wirre Gedankenwelt
  1. posts/

Tell me about the why

Today I came around this piece of code and struggled at the comment.

urlbase64() {
    # urlbase64: base64 encoded string with '+' replaced with '-' and '/' replaced with '_'
    openssl base64 -e | anti_newline | sed -r 's/=*$//g' | tr '+/' '-_'
}

Of cource, this comment is not entirely useless, since it tells me what the function is going to do.

But the important information is missing: The why. Tell me about why you are doing it. Maybe also why you are doing it this was. Most of the time, it is much more difficult for the reader to figure out the why. The what and the how are often obvious.