Well, in that case, I would rather call the class itself "OutstandingDocumentsToOcrEngine" and leave that part out of the upload methods names - but hey, that's just me.
I find it very hard to read these long names, and I don't think it's because I'm a non-native English speaker, (after all, I've been reading and writing PascalCase/camelCase code for over two decades now).
I mean, compare how easy it is to read
Upload documents and create batch in ocr if does not exist
Fantastic points, especially on making it a class instead of a set of methods. It's not you at all!
My example may be trivial, but the crux of what I was trying to get across is small methods with descriptive names are better than one long method which is difficult to follow.
I put this post out hoping to start a discussion and that's exactly what we've got. :)
You might also want to read Stop Writing Code Comments. I can't say I totally agree with this, since I really do believe that comments should be used in code (Especially xml documentation for public APIs, but not only). In fact, in a comment to another post a few days ago I was telling how good commenting habits from the old me saved the current me literally days of work - but yeah, as a rule of thumb, he does have a valid point: good code is a code that's easy to read even without comments.
I agree wholeheartedly with the zero comments within code. I think if you need to add a comment to describe a line of code, then the line of code isn't as clean as it could be.
vardocumentList=this._service.Get();// Retrieve all outstanding documents from the databaseforeach(vardocumentindocumentList){}
Well, in that case, I would rather call the class itself "OutstandingDocumentsToOcrEngine" and leave that part out of the
upload
methods names - but hey, that's just me.I find it very hard to read these long names, and I don't think it's because I'm a non-native English speaker, (after all, I've been reading and writing PascalCase/camelCase code for over two decades now).
I mean, compare how easy it is to read
vs
It's not just me, right?
Fantastic points, especially on making it a class instead of a set of methods. It's not you at all!
My example may be trivial, but the crux of what I was trying to get across is small methods with descriptive names are better than one long method which is difficult to follow.
I put this post out hoping to start a discussion and that's exactly what we've got. :)
You might also want to read Stop Writing Code Comments. I can't say I totally agree with this, since I really do believe that comments should be used in code (Especially xml documentation for public APIs, but not only). In fact, in a comment to another post a few days ago I was telling how good commenting habits from the old me saved the current me literally days of work - but yeah, as a rule of thumb, he does have a valid point: good code is a code that's easy to read even without comments.
I agree wholeheartedly with the zero comments within code. I think if you need to add a comment to describe a line of code, then the line of code isn't as clean as it could be.
vs
The second one is longer, but I'm completely ok with that for the gain in legibility.
Public API's are a whole different matter, and as far as I'm concerned should always be fully documented with XML comments.