In python we designate internal function/ private methonds with an underscore at the beginning. Should these functions be documented with docstrings(is it required?)? (the formal documentation i mean, not the one helping the code-reader to understand the code) What is common practice for this?
Asked
Active
Viewed 1.4k times
1 Answers
47
Lo, I quote from PEP 8, the wise words of which should be considered law. Upon this very topic, PEP 8 saith:
- Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the "def" line.
Chris Morgan
- 86,207
- 24
- 208
- 215
-
3Hey thanks. Are the """ necessary? or # style comments are okay? Its not that I am against """ styled comments, but am just curious. – 0xc0de Oct 07 '11 at 12:50
-
4@0xc0de: A docstring will be available in the parsed code when you do help(function_name) in the interactive interpreter - it's really a literal string, not a "comment style". A comment is just that, a comment, stripped from code during parsing. – millimoose Oct 07 '11 at 13:00
-
7@0xc0de: Also, you don't need to use triple-double-quotes for docstrings - they're just strings, not special syntax. So you can use single or double quotes, and the tripling is to let you embed newlines in the comment text. – millimoose Oct 07 '11 at 13:04
-
Thanks. I checked with " and ', you are right, I didn't know this. – 0xc0de Oct 07 '11 at 13:19
-
@0xc0de A little compliance with rules is good. But not trying to do it all. What do you feel living in a country which is full of rules? There should be some flexibility. Yeah I exaggerated, but AIM for simplicity, Not following the rules. – Amir Hossein Baghernezad Mar 09 '18 at 08:35
-
@TechJS Following rules and guidelines like PEP makes your code maitainable not only while in a team but even for yourself. It's kinda painful to work with someone who finds PEP guidelines unnecessary (they are so easy to follow, it needs a strong reason not to follow these) as that means difficulties in extending, debugging and fixing that code. – 0xc0de Mar 09 '18 at 08:41
-
@0xc0de OK You are right, I dont know how much experience you have but for example take writing comments as an example, Can you imagine how much time can get wasted simply by taking time to write useful comments? I think as twice as programming time. You can instead create meaningful method names, meaningful class names (even that long, like JAVA guys do). Hey! We are in agile era! Talk to people about what it does if the name does not describe it. Writing comments for each and all methods IS A WASTE. Although I am OK with writing for just a few of them but not ALL of them. – Amir Hossein Baghernezad Mar 09 '18 at 08:58
-
PEP doesn't enforce writing docstring for every function, only for public members. Think about a library or an API function, it's annoying to find something like `sorted` undocumented and trying to figure out what args do w/o docs. Meaningful names are a must, no doubt, but there are practical limitations to that. I personally have spent more time thinking about names than for comments. Comments are supposed to be added where you think your code isn't absolutely clear (to reader) eg workarounds. You'll later thank your comments for saving hours, so writing them is rather an investment. Peace. – 0xc0de Mar 09 '18 at 09:12
-
@TechJS Spend time choosing meaningful names. But when it’s not absolutely obvious beyond a shadow of doubt how you should use something, which frankly is almost always in dynamic languages (it’s a little less often so in statically typed languages) use doc comments. In practice, it’s easiest to follow a rule with no nuance, and just *always* write comments on public methods. Remember also that comments are great for saying *why*, as distinct from *what*. Time spent documenting all the things is only wasted on one-off things that will never, ever be referred to again. – Chris Morgan Mar 09 '18 at 11:04