Should I write more descriptive function names or add comments?

Question

This is an agnostic language question, but I wander what people prefer in terms of readability and maintainability ... My hypothetical situation is that I write a function that sets the sequence, returns a copy with all the duplicate element deleted and the order is canceled.

/* *This is an extremely well written function to return a sequence containing *all the unique elements of OriginalSequence with their order reversed */ ReturnSequence SequenceFunction(OriginalSequence) {...} 

OR

 UniqueAndReversedSequence MakeSequenceUniqueAndReversed(OriginalSequence) {....} 

The above should be a clear example of using comments in the first instance or using very verbose function names in the second to describe the actions of the function.

Greetings

Richard

Answer 1

I prefer the name of the verbose function, as this makes the site's website more readable. Of course, some function names (like your example) can be very long.

Perhaps the best name for your example function would be ReverseAndDedupe . Oh, oh, now it’s a little more clear that we have a function with two responsibilities *. It might be better to divide this into two functions: Reverse and Dedupe .

The call site is now even more readable:

 Reverse(Dedupe(someSequence)) 

* Note . My rule of thumb is that any function that contains an “and” in a name has too many responsibilities and should be divided into separate functions.

Answer 2

Personally, I prefer the second way - it’s easy to see what it does from the name of the function, and because the code inside the function is well written anyway, it will be easy to work out what happens inside it.

The problem that I find with the comments is that they are out of date very quickly - there is no compilation time check to ensure that your comment is correct!

In addition, you do not get access to the comment in those places where the function is actually called.

Very subjective question though!

Answer 3

Ideally, you would make a combination of the two. Try to keep your method names concise but descriptive enough to get an idea of ​​what it is going to do. If there is any possibility of a lack of clarity in the method name, you should have comments to help the reader in the logic.

Answer 4

Even with descriptive names, you should still be short. I think that you have too much in this example. I would write

 UniqueSequence Reverse(Sequence) 

Answer 5

I would probably do one of them:

• Name it ReverseAndDedupe (or DedupeAndReverse , depending on what it is). I would only expect Dedupe to save the first occurrence and discard later ones, so the two operations do not commute) All functions make some kind of postcondition true, so Make can certainly go to shorten the name too long. As a rule, functions do not need to be assigned to the types on which they work, and if they are then they should be in a consistent format. Therefore, Sequence can probably be removed from your proposed name, or if it cannot, I would probably call it Sequence_ReverseAndDedupe .

• Do not create this function at all, make sure that callers can either do Reverse(Dedupe(x)) or Dedupe(Reverse(x)) , depending on what they really want. There is no longer any code for them to write, so the only question is whether there is any tricky optimization that applies only when you do both at the same time. Avoiding an intermediate copy may pretend to be, but the general point is that if you cannot name your function concisely, make sure there is a good reason why it does so many different things.

• Call it ReversedAndDeduped if it returns a copy of the original sequence - this is the trick I chose from Python, where l.sort() sorts the list l in place, and sorted(l) doesn't change the list l at all.

• Give it a name specific to the domain in which it was used, instead of trying to make it so generic. Why am I deduplicating and reversing this list? Perhaps there is a certain term of art, which means a list in this state or some function that can be performed only in such a list. Therefore, I could call it "Renuberate" (because the inverted, highlighted list is known as the "in Renuberated form" or "MakeFrobbable" list (because Frobbing requires this format).

I would also comment on this (or much better, document it) to explain what type of deduplication it guarantees (if there is one, perhaps the implementation remains free to remove any deceptions while it receives them).

I would not comment on this “very well written”, although I could comment on “highly optimized” to mean that “it’s very difficult to work with this code, but it goes like clappers, please don’t touch it without running all the performance tests” .

I don’t think that I would like to get to the function names of 5 words, although, I think, in the past I was.

Answer 6

I comment on where there is an explanation so that the descriptive name cannot adequately convey. If there is some peculiarity in the library that made me do something that seems non-standard, or value when discarding the inline comment, I will do it, but otherwise I rely on well-named methods and do not comment much, except while I'm writing code, and this is for me. They are deleted when this is done, as a rule.

Generally speaking, function header comments are just a few lines of support and require the reader to look at both the comment and the code, and then decide that this is correct if they do not match. Obviously, truth is always in code. A comment may say X, but comments are not compiled into machine code (usually), so ...

Comment on when necessary, and make it a habit to name things well. This is what I do.