5 ms·

Well, I believe that any code should be readable enough so that the comments like below wouldn't be required. # splits a Wikipedia section into sentences # and

Well, I believe that any code should be readable enough so that the comments like below wouldn't be required. # splits a Wikipedia section into sentences # and then chunks/tokenizes each sentence If I had interviewed the author, I would have asked him what's the purpose of commenting like that.

aldarn 10y ago
I believe it's easier to read a native language than code. I would also counter there is no harm to comments like this so just because you don't find it useful doesn't mean someone else won't.
- sAbakumoff 10y ago
  Okay. My point is in that in the real job you don't have time for writing this type of comments. Instead you have your current task to work on, the issue that was re-opened and needs to be revisited, the bug to argue with QA about, the deadline to discuss with PM, the code-review to do ASAP. You simply don't have time to write the perfect code that is full of the comments in the "native language".
  - yosamino 10y ago
    This rather sounds like you don't have the time to not do it. Imagine using the time that spent on "re"-visiting "re"-opened bugs that are vague enough to be argued about on writing code that doesn't need these "re"s in the first place. I contend that that might be a difficult place to get to especially because it's a team effort as well, but I feel it's more productive and less stressful to work like that.
    - sAbakumoff 10y ago
      I am too long in IT to imagine anything like that.
cancancan 10y ago
One of the purposes is to write down what you need to do as comments, and then implement each part. Like pseudo code. Saying you don't have time for it is like saying you don't have time to think through what you're trying to do.
- sAbakumoff 10y ago
  It's entirely possible to think through what you're trying to do without writing the code comments. I prefer good old-fashioned pen and paper for example.
  - cancancan 10y ago
    Of course, but you don't share those papers with us :) I like those kinds of comments a lot. In a good editor it's so easy to just scan a lot of code and understand what's what. You could look at something you or someone else wrote years ago, in different style, different paradigm, different language, ... and still have a perfectly clear picture of what code does in no time. To each his own I guess.
sethammons 10y ago
That particular comment seems OK. In general, one should make the code readable to the point of not needing a comment. Comments can rot over time in legacy systems. Somethings really benefit from a comment, however I feel the following snippet is a better example of a comment that should not exist as it does not serve to clarify the code and is just a direct English translation of the simple code: # Iterate through article's sections for section in self.page.sections:
- sAbakumoff 10y ago
  Yeah that's clearly redundant
tedmiston 10y ago
The project is cool and I know the code is not necessarily the point. That said, if I were being picky, I'd ask why the author chose not to use docstrings. The code itself is fine but not very Pythonic. There are small inconsistencies* that running pycodestyle [1] once would have caught and could be fixed quickly — I recommend OP consider that. *Mostly related to: whitespace / spacing, indentation, mixing single quotes and double quotes, magic numbers, naming conventions [1]: https://pypi.python.org/pypi/pycodestyle https://pypi.python.org/pypi/pycodestyle

aldarn 10y ago

I believe it's easier to read a native language than code. I would also counter there is no harm to comments like this so just because you don't find it useful doesn't mean someone else won't.

sAbakumoff 10y ago
Okay. My point is in that in the real job you don't have time for writing this type of comments. Instead you have your current task to work on, the issue that was re-opened and needs to be revisited, the bug to argue with QA about, the deadline to discuss with PM, the code-review to do ASAP. You simply don't have time to write the perfect code that is full of the comments in the "native language".
- yosamino 10y ago
  This rather sounds like you don't have the time to not do it. Imagine using the time that spent on "re"-visiting "re"-opened bugs that are vague enough to be argued about on writing code that doesn't need these "re"s in the first place. I contend that that might be a difficult place to get to especially because it's a team effort as well, but I feel it's more productive and less stressful to work like that.
  - sAbakumoff 10y ago
    I am too long in IT to imagine anything like that.

cancancan 10y ago

One of the purposes is to write down what you need to do as comments, and then implement each part. Like pseudo code. Saying you don't have time for it is like saying you don't have time to think through what you're trying to do.

sAbakumoff 10y ago
It's entirely possible to think through what you're trying to do without writing the code comments. I prefer good old-fashioned pen and paper for example.
- cancancan 10y ago
  Of course, but you don't share those papers with us :) I like those kinds of comments a lot. In a good editor it's so easy to just scan a lot of code and understand what's what. You could look at something you or someone else wrote years ago, in different style, different paradigm, different language, ... and still have a perfectly clear picture of what code does in no time. To each his own I guess.

sethammons 10y ago

That particular comment seems OK. In general, one should make the code readable to the point of not needing a comment. Comments can rot over time in legacy systems. Somethings really benefit from a comment, however I feel the following snippet is a better example of a comment that should not exist as it does not serve to clarify the code and is just a direct English translation of the simple code: # Iterate through article's sections for section in self.page.sections:

sAbakumoff 10y ago
Yeah that's clearly redundant

tedmiston 10y ago

The project is cool and I know the code is not necessarily the point. That said, if I were being picky, I'd ask why the author chose not to use docstrings. The code itself is fine but not very Pythonic. There are small inconsistencies* that running pycodestyle [1] once would have caught and could be fixed quickly — I recommend OP consider that. *Mostly related to: whitespace / spacing, indentation, mixing single quotes and double quotes, magic numbers, naming conventions [1]: https://pypi.python.org/pypi/pycodestyle https://pypi.python.org/pypi/pycodestyle