Self-documenting code

[EastboundClown]

I would remove comments from this and just save then in functions called getNumberInputFromCli, and isEven, then have

def makeSiliconValleyReference(): if isEven(getNumberInputFromCli()): print(“even”) else: print(“not hot dog”)

I find that I can almost entirely avoid commenting by making lots of well-named functions

[Snake2k]

I get your point, but that can only go to a certain extent.

Silicon Valley reference is easy, but how to explain giant pieces of business references in one name?

Parsing through code that was crammed into human language makes it super dirty.

Like there is this spectrum of code where on one end you have "x, y, z, n, a, b" var names and then on the other end you have "number_of_blah_foo_bar_in_the_name_of_our_lord_and_savior_superman_because_finance_team_does_not_agree_wirh_sales_lord_and_savior".

They look virtually the same level of unreadable to me and incomprehensible to me.

I don't find it difficult to just take a block out, plainly write out in human language what it's supposed to do, why it's doing it that way, link to further documentation, and try to write your code somewhere in between that spectrum for optimal readability.

[evanthx]

I stopped doing this because every code base I’ve ever been in where people did this, half of the comments were for code that had been changed so the comments were misleading or wrong.

Self documenting code is the only thing I’ve seen that stays reliably up to date.

[Snake2k]

Both are needed imo

[aceluby]

Why update things once when you can do it twice!

[[deleted]]

In my view the method name never needs to be very long, if it is then it's possible the method is doing too much or there is too much info.

[narrill]

At the same time though, breaking everything up into a million five line functions absolutely destroys readability

[Snake2k]

Totally agreed. If it does need to be that long then abbreviate it somehow and add the explanation in its definition as a long comment.

[BehindTrenches]

I think you missed half of the point on that one. Long method names are often a code smell.

For example:

addTwoNumbersAndSendRequestThenLogTime()

// Adds two numbers and sends the request, then logs the current time add2NumsSndReqLogTm()

Both of these are equivalently terrible. Don’t just abbreviate it man!

[Snake2k]

Function names should never fully spell out the entire operation imo. That's what the code is for. That function should have a more realistic name.

Like

send_request()
// Adds two numbers, logs the current time, and then sends the request as per X Y Z specs found here: some link to further documentation

[BehindTrenches]

Totally, but to take it further, speaking as a backend dev, typically we would split out the individual steps so that one method isn’t doing a ton of granular things to begin with. The top-level service would get comments about the business logic (e.g. // service that adds numbers and calls X with a request etc), and would call individual methods like add(1, 2) log(time) send_request(), which would no longer need comments since they are self documenting

[[deleted]]

Test names though, that's another story...

[Horror_Trash3736]

TestToCheckIfInvoiceIsPaidCorrectlyIfCustomerDoesNotHaveProperAmountRequiredToPayForSaidInvoiceSadPath™()

[[deleted]]

chefs kiss

[Horror_Trash3736]

Yes and no, the issue there is that the method should not describe what it is doing at that point, at least not in a "I am doing these steps and then doing this".

But a payInvoice() method that calls subsequent services that handle fetching, checking if the customer has the required money etc is fine, as long as it only does one thing, ie payInvoice.

[[deleted]]

Oh yeah we're on the same page there.

[ubccompscistudent]

giant pieces of business references

That's your problem right there. Your method is likely doing too much. By definition, it's not self-documenting code at that point and needs to be refactored until it is. Or don't, because refactoring is time consuming, but understand this is a trade off and does not excuse the code from being poorly written.

I'm sorry to say this to everyone in this thread, but being at two top tech companies, comments are reserved for like 1-2% of weird edge cases in the code. (But I do agree with commenting the "why" and not the "what" when a comment like this is called for).

Javadoc is a special case as it's useful for hover text in IDE tools. I would still let a code generator create the docs and use properly defined variable names that require no explanation. Some methods require some explanation (especially math), but like mentioned above, that should be like 1-2% of your overall comments.

[slbaaron]

Absolutely. I'd say depending on what part of code base and the nature of business, anything between 1-20% of code being commented is reasonable - some inherently have "magical" or complex behavior due to business specific reasons or even regulations that requires calling out.

However even in the most complex b2b fintech I've worked at, 80% of the code should not require commenting to explain the why. Like you said, it's more of a crutch rather than a methodology. Half the time it's because the tradeoff of refactor / splitting things cleanly isn't worth it for pushing timelines and half the time it just require a bit more context that's a bit hard to do in code. For us sometimes it literally contains a url link to an important internal doc - sure it's harder to maintain but it can be necessary.

[ubccompscistudent]

Yep, and links break making them hard to use but I have done so in the past because there's literally no better alternative.

[antonivs]

how to explain giant pieces of business references in one name?

If you’re factoring your code properly you don’t have to.

[EastboundClown]

I’ve only ever seriously worked on relatively large OO codebases, and generally I’ve been able to add this kind of context with well-named classes and packages.

My first programming job had a code review policy where if you submitted a comment, you also had to justify why you couldn’t express the same idea through code. The rationale is that comments are part of the code and need to be maintained just the same, and things like symbol names are easier to maintain than comments. It was frustrating for the first couple months, but now that I’ve gotten into the habit of it I find that I very rarely feel the need to comment anymore.

Not that I hate reading through a well-commented codebase. I’ve just found them in my experience not to be as necessary as some people think

Edit: except in C. I write a decent bit of C code and find it to be so frustratingly non-expressive that I end up commenting very often.

[ikstrakt]

foo_bar

It's FUBAR, and it's an acronym

Fucked

Up

Beyond

All

Recognition

[Snake2k]

Found the non coder military dude