Skip to main content
Software Engineering

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

Required fields*

6
  • 1
    Class names are part of the code, those are exactly the things in the code where choosing them meaningful and consistently matters. The "one source of truth" metapher is a recommendation against too much superfluous documentation, not against choosing class names following some convention. Commented Mar 4, 2021 at 11:02
  • @DocBrown indeed, strictly speaking, comments are also part of the code. I’ve clarified by extending my summary sentence. It’s a about redundancy and possible inconsistencies. Introducing a prefix in the name redundantly expresses what the class definition already does. This redundancy is superfluous. Moreover it may be misleading, since the compiler doesn’t check consistency of the name with the language constructs. Finally it is ambiguous: some reader will understand BaseCar as a minimalistic car without necessarilybeing abstract Commented Mar 4, 2021 at 12:38
  • And to this I would add: document your thoughts and decisions, whatever they may be, as a permanent part of the project's ongoing history and chronology. If, as is undoubtedly the case, "the team debated it," capture that. Formally. Commented Mar 5, 2021 at 1:09
  • 1
    @MikeRobinson There are plenty of situations where there are two possible ways, and one of them looks a lot better but has some hidden problems that are bad and unfixable. Without documentation, every year or two someone will come and say "why didn't we use the much better method, I'll change that" until they figure out the hidden problems and go back to the old way. Commented Mar 9, 2021 at 19:19
  • @gnasher729 I fully agree. Booch in this book of 1992 already explained that it makes sense to document things that cannot or not easily be found in code, such as complex interactions or rationale of important design decisions. My answer was focused on about the rest, and particularly misleading naming: nobody will check a naming in a design decision, especially of there seems to be nothing special about it. Commented Mar 9, 2021 at 20:12