| 4.Coding.rst (9e1f08607f904e89568e197f4e30985484a87fd7) | 4.Coding.rst (1dc4bbf0b268246f6202c761016735933b6f0b99) |
|---|---|
| 1.. _development_coding: 2 3Getting the code right 4====================== 5 6While there is much to be said for a solid and community-oriented design 7process, the proof of any kernel development project is in the resulting 8code. It is the code which will be examined by other developers and merged --- 344 unchanged lines hidden (view full) --- 353Internal API information for many subsystems is documented by way of 354specially-formatted comments; these comments can be extracted and formatted 355in a number of ways by the "kernel-doc" script. If you are working within 356a subsystem which has kerneldoc comments, you should maintain them and add 357them, as appropriate, for externally-available functions. Even in areas 358which have not been so documented, there is no harm in adding kerneldoc 359comments for the future; indeed, this can be a useful activity for 360beginning kernel developers. The format of these comments, along with some | 1.. _development_coding: 2 3Getting the code right 4====================== 5 6While there is much to be said for a solid and community-oriented design 7process, the proof of any kernel development project is in the resulting 8code. It is the code which will be examined by other developers and merged --- 344 unchanged lines hidden (view full) --- 353Internal API information for many subsystems is documented by way of 354specially-formatted comments; these comments can be extracted and formatted 355in a number of ways by the "kernel-doc" script. If you are working within 356a subsystem which has kerneldoc comments, you should maintain them and add 357them, as appropriate, for externally-available functions. Even in areas 358which have not been so documented, there is no harm in adding kerneldoc 359comments for the future; indeed, this can be a useful activity for 360beginning kernel developers. The format of these comments, along with some |
| 361information on how to create kerneldoc templates can be found in the file 362Documentation/kernel-documentation.rst. | 361information on how to create kerneldoc templates can be found at 362:ref:`Documentation/doc-guide/ <doc_guide>`. |
| 363 364Anybody who reads through a significant amount of existing kernel code will 365note that, often, comments are most notable by their absence. Once again, 366the expectations for new code are higher than they were in the past; 367merging uncommented code will be harder. That said, there is little desire 368for verbosely-commented code. The code should, itself, be readable, with 369comments explaining the more subtle aspects. 370 --- 43 unchanged lines hidden --- | 363 364Anybody who reads through a significant amount of existing kernel code will 365note that, often, comments are most notable by their absence. Once again, 366the expectations for new code are higher than they were in the past; 367merging uncommented code will be harder. That said, there is little desire 368for verbosely-commented code. The code should, itself, be readable, with 369comments explaining the more subtle aspects. 370 --- 43 unchanged lines hidden --- |