This is just a question to think about.
When you write technical documentation and programming comments, do you ever find yourself writing run-on sentences in order to be more precise?
Is packing more technical information into one sentence better than creating many little sentences each with a little bit of technical information?
I know it's better to have lots of little classes in their own little files. Perhaps this doesn't apply to writing?
Not if I can help it :)
Think about it this way - what is the purpose of technical documents?
Right - to communicate something technical - and possibly quite involved/complex.
Now imagine you are listening to someone explain something to you that you are struggling to follow - they don't stop, they don't pause, information is flooding into your brain faster than you can take it in, you end up following nothing.
It's the same with reading - too much information without a break, and the reader will generally either skip it without having read it properly, or repeatedly read that sentence until they can finally hold it all in their heads at once and understand it.
Don't do this to your readers! Put yourself in their shoes - write it as you would wish to read it.
Short, succint sentences are best - you're not writing prose.
Unfortunately good writing skills appear to be rare among many technical people including programmers. The bonus is that with a little investment in improving your writing skills will make you stand out.
Consider this:
A single 40-word sentence that someone reads 4 times before comprehending it that too with some doubts and in the end the sentence is ignored because "there are more to follow"...
Another alternative:
Four 10-word sentences.
Understandable in (at most) 2 readings.
Reader's happy and of course, understands what you wrote.
Is packing more technical information into one sentence better than creating many little sentences each with a little bit of technical information?
To some extent, this is a language dependent question. From the point of view of English, it's generally very poor practice to overload sentences although there is some more scope in, for example, German.
Consider other ways of presenting the information to promote clarity. For example:
(I appreciate that pics may be hard to use in code comments)
