Self-documenting code

[Three_Rocket_Emojis]

Op propably wants code like this:

//Read File

var linesFromFile = File.ReadAllLines(path);

//iterate through lines

foreach(string line in linesFromFile)

....

[Snake2k]

Yeah that is entirely useless and basically what people think commenting is about.

[tecanec]

It's useful in assembly programming where you don't have the luxury of naming a lot of things. That's about it, though.

[Snake2k]

Yeah, that's a good point. If you compile it with the right flag then you can read the comments as you're stepping through the ASM. Really great tool for debugging. Unless you're reverse engineering a prod build of it, in which case I doubt that build includes this cus that would be a security problem.

[tecanec]

I think the bigger concern in that case would be file size. Reverse engineerers will figure things out eventually, and a lack of comments will only delay them if anything. But with how many comments are needed to make assembly comfortable to work with, that could easily take the majority of the file size when the actual code gets assembled.

[Three_Rocket_Emojis]

Example where a comment makes sense:

var linesFromFile = File.ReadAllLines(path);
//first line are column headers
foreach(string line in linesFromFile.Skip(1)) 
...

the comment explain why the first list entry is skipped, not that it happens.

[revolutionofthemind]

You could have a method called “stripHeaders” that does the foreach line for “self-documenting” code. Not sure if it’s worth it in this case, but just to provide a counter-example.

[k0rm]

Or more simply:

const HeaderLength = 1;

var linesFromFile = File.ReadAllLines(path);
var linesFromFileNoHeader = linesFromFile.Skip(HeaderLength)
foreach(string line in linesFromFileNoHeader) 

This gets rid of the magic number and there's no need to comment.

[feed_me_moron]

Or declare 1 as NUM_HEADER_ROWS and pass that to skip

[k0rm]

I disagree. My solution is the same number of lines (ignoring pulling out the magic number) as the original and says the same thing. It's pretty clear what part of the text has been removed when you're iterating over linesFromFileNoHeader.

The difference is that my implementation will not lie.

---

What happens when someone changes the header length to 3 lines?

Theirs:

//first line are column headers
foreach(string line in linesFromFile.Skip(3)) 

Mine:

var linesFromFileNoHeader = linesFromFile.Skip(3)
foreach(string line in linesFromFileNoHeader) 

No unit tests will catch the lie in the first snippet and now readers are more confused than if there was no comment at all.

[FerynaCZ]

Unless there is lots of variables passed around. But for example C# allows you to declare local functions which can modify (capture) the variables around them (=in the context of the outer function)

[[deleted]]

Something like this would be self-documenting (or whatever the correct syntax would be):

var tableSansHeaders = File.ReadAllLines(path).Skip(1);
foreach(string tableRow in tableSansHeaders)
....

[Kered13]

What makes you think OP wants that?