Light Mode
Dark Mode
[feedback] Comments vs clearance

Hello everybody, (@edit for lazy: working hyperlinks are in comment below)

Lately, reading my old codes and looking at other's publications at the top of "Clear" cathegories, I have encountered a problem. There are some great commented codes (and it's great to comment your code) explaining everything they do, but I have the notion that it's at the cost of clearance of the code. I have caught myself skipping reading the code just because it had too much commentary. There are some extreme cases where green flood devours everything making it difficult to grasp the code.

Example: http://www.checkio.org/mission/feed-pigeons/publications/Lasica/python-3/binary-search-clear-speedy-and-commented/

So I've thought, that it doesn't have to be like that, as comments are great, but being able to take a quick look at the whole code without green stuff obfuscating your view and disturbing grasping the core of the code is also really important.

There are two solutions to both encourage commenting while not disturbing clearance:

  1. Easier one: create a button to toggle showing comments in the code stripping them: at the end of the statements, and hiding lines (not changing row numeration) containing solely comments and whitespaces. As all default settings are really important, and some of interface features remain undiscovered by many users, I'd suggest that default state of showing comments should be as it is now - show all.

    By the way, this is a good occasion to get our python programming community a new easy, educational, practical task to program :P - strings are extra tricky

  2. More difficult extention: auto-detect comments to make the code viewer interactive, showing where it hid comments and make them be toggable both selectively and collectively (with the button mentioned in 1.)

PS: talking about clearance of the code and auto-formatting it, the generic code appended to every coding workspace also usually obfuscates the view and litters the code. It could be filtered in publications. Example of problem: http://www.checkio.org/mission/open-labyrinth/solve/

  • comments
  • feature
Created: April 26, 2014, 5:58 p.m.
Updated: April 27, 2014, 8:32 a.m.
1
12
User avatar
Lasica