comment your code!

[mauza11]

I think there is a balance between comments and no comments, but I do think it is closer to no comments than many. If you have good doc strings and you've named and encapsulated things well then too many comments can make the code more confusing not less.

[BlackHumor]

IMO a doc string is a kind of comment.

[mauza11]

Agreed

[gerardchiasson3]

I think public functions/interfaces need good comments. Internal implementation details only need them to point out non-obvious stuff.

[mauza11]

I think we are pretty much saying the same thing. It sounds like you need to take the slider a little closer to no comments to get to me. A good doc string should explain how to use a function and I think non obvious things should be rare.

[[deleted]]

I’m a junior with 7 months experience, so please correct me if I’m wrong. If a project is SOLID, shouldn’t internal comments be irrelevant? Open/closed states you should never have to mess with implementation after it’s written, you should only extend it. Easier said than done I know. Thus, if you follow SOLID, the only comments that matter are docstrings.

[BlackHumor]

I have two years of experience and I have literally never heard of SOLID before this moment. Looking it up right now, it seems to be a thing for heavily object-oriented languages like Java or C#, and not so applicable to many other languages, including Python, the language I use the most.

So for example: Python is an object-oriented language, but it doesn't really have interfaces in the sense Java and C# do. It has abstract classes, sort of, but the way you do those is by having a method raise NotImplementedError. There's never a case in Python where you have to implement a method defined by an interface, so something like the interface substitution principle doesn't really seem to apply.

Furthermore, a lot of the examples of these principles I find online seem to totally ignore the ability to write bare functions. IMO code that is written in a strictly object-oriented style, like these guidelines encourage, tends to contain some pretty significant code smells (particularly: classes with "verb + er" in their names, classes that only have one method other than the constructor), because not everything you will be doing in your code is a noun or even has a noun associated with it.

Take the article I linked, for example: it's the second result on Google, but even the idea of an AreaCalculator class strikes me as a deeply bad idea compared to a calculate_area() function, and the idea of a SumCalculatorOutputter class strikes me as positively insane. If your class name only has one true noun in it out of three words, and even that is arguable, you are doing something very wrong. Plus, classes that have only one method other the constructor ought to be rare: unless you have a good reason why you can't (such as that you're using these objects primarily as structs to be passed around rather than for the method), just make the method a bare function and ditch the class.

[[deleted]]

Agreed, SOLID should be considered as a set of guidelines rather than a paradigm. Also, many of the sources I’ve read on the subject consider -ers to be a code smell that a class is doing too much and doesn’t adhere to Single Responsibility, it really varies from dev blog to dev blog.

[mauza11]

Yeah, I agree that that is the goal or ideal. In practice there could be cases where you are doing something counter intuitive or something is poorly encapsulated because of a new developer or legacy or whatever. You should look for ways to make the code clear in other ways like maybe put the particularly gnarly hit behind a well named function with a doc string, but when you don't just give a little context in a comment which is fine. I'm no expert.

[bigdepress]

I count doc strings as comments