Hacker News Reader

Comment by Cyph0n | Hacker News Reader

Excellent idea. There are a lot of interesting ways to improve this, but you have an MVP running, which is a good start.

Regarding your codebase: clear and to-the-point code, well commented, and helpful commit messages. Including a `requirements.txt` is a plus.

Good job, keep it up!

View on HN

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.

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.

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".

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.

I am too long in IT to imagine anything like that.

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.

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.

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.

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:

Yeah that's clearly redundant

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

Reply on news.ycombinator.com