Questa è solo una domanda a cui pensare.
Quando scrivi documentazione tecnica e commenti di programmazione, ti ritrovi mai a scrivere frasi run-on per essere più preciso?
È meglio impacchettare più informazioni tecniche in una frase piuttosto che creare tante piccole frasi ciascuna con un po 'di informazioni tecniche?
So che è meglio avere un sacco di piccole classi nei loro piccoli file. Forse questo non si applica alla scrittura?
Non se posso aiutarlo:)
Pensaci in questo modo - qual è lo scopo dei documenti tecnici?
Giusto - per comunicare qualcosa di tecnico - e possibilmente abbastanza coinvolto / complesso.
Ora immagina che stai ascoltando qualcuno che ti spiega qualcosa che stai faticando a seguire - non si fermano, non si fermano, le informazioni si riversano nel tuo cervello più velocemente di quanto tu possa prendere, finisci in seguito a nulla.
È lo stesso con la lettura - troppe informazioni senza interruzioni, e il lettore generalmente salta senza leggerlo correttamente, o legge ripetutamente quella frase fino a quando riescono finalmente a tenere tutto in testa in una volta e capirlo .
Non farlo ai tuoi lettori! Mettiti nei loro panni: scrivilo come vorresti leggerlo.
Le frasi brevi e succinte sono le migliori - non stai scrivendo in prosa.
Sfortunatamente le buone capacità di scrittura sembrano essere rare tra molte persone tecniche, inclusi i programmatori. Il vantaggio è che con un piccolo investimento nel migliorare le tue capacità di scrittura ti faranno risaltare.
Considera questo:
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"...
Un'altra alternativa:
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?
In una certa misura, questa è una domanda dipendente dalla lingua. Dal punto di vista dell'inglese, è generalmente una pratica molto scarsa sovraccaricare le frasi, anche se c'è un po 'più di spazio, per esempio, in tedesco.
Considera altri modi di presentare le informazioni per promuovere la chiarezza. Ad esempio:
(Apprezzo che le foto possano essere difficili da usare nei commenti al codice)
Leggi altre domande sui tag readability comments documentation writing