mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-12-17 20:05:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc(dev_style.txt): misc updates

Browse Source
This commit is contained in:
Justin M. Keyes
2021-09-23 06:58:39 -07:00
parent 5f49d0efee
commit c05b10748c
1 changed files with 170 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
runtime/doc/dev_style.txt
View File

@@ -4,9 +4,11 @@
NVIM REFERENCE MANUAL NVIM REFERENCE MANUAL
Neovim style guide *dev-style* Nvim style guide *dev-style*
This reference describes the neovim style guide. This is style guide for developers working on Nvim's source code.
License: CC-By 3.0 http://creativecommons.org/licenses/by/3.0/
Type |gO| to see the table of contents. Type |gO| to see the table of contents.
@@ -33,16 +35,16 @@ Header Files *dev-style-header*
The #define Guard ~ The #define Guard ~
All header files should have `#define` guards to prevent multiple inclusion. All header files should have `#define` guards to prevent multiple inclusion.
The format of the symbol name should be `NEOVIM_<DIRECTORY>_<FILE>_H`. The format of the symbol name should be `NVIM_<DIRECTORY>_<FILE>_H`.
In foo/bar.h: In foo/bar.h:
> >
#ifndef NEOVIM_FOO_BAR_H #ifndef NVIM_FOO_BAR_H
#define NEOVIM_FOO_BAR_H #define NVIM_FOO_BAR_H
... ...
#endif // NEOVIM_FOO_BAR_H #endif // NVIM_FOO_BAR_H
< <
@@ -88,23 +90,28 @@ variable is and what it was initialized to. In particular, initialization
should be used instead of declaration and assignment, e.g. > should be used instead of declaration and assignment, e.g. >
int i; int i;
i = f(); // Bad -- initialization separate from declaration. i = f(); // BAD: initialization separate from declaration.
int j = g(); // Good -- declaration has initialization. int j = g(); // GOOD: declaration has initialization.
============================================================================== ==============================================================================
Neovim-Specific Magic Nvim-Specific Magic
clint ~ clint ~
Use `clint.py` to detect style errors. Use `clint.py` to detect style errors.
`clint.py` is a tool that reads a source file and identifies many style `src/clint.py` is a Python script that reads a source file and identifies
errors. It is not perfect, and has both false positives and false negatives, style errors. It is not perfect, and has both false positives and false
but it is still a valuable tool. False positives can be ignored by putting `// negatives, but it is still a valuable tool. False positives can be ignored by
NOLINT` at the end of the line. putting `// NOLINT` at the end of the line.
uncrustify ~
src/uncrustify.cfg is the authority for expected code formatting, for cases
not covered by clint.py. We remove checks in clint.py if they are covered by
uncrustify rules.
============================================================================== ==============================================================================
Other C Features *dev-style-features* Other C Features *dev-style-features*
@@ -394,10 +401,10 @@ instance: `my_exciting_local_variable`.
For example: > For example: >
string table_name; // OK - uses underscore. string table_name; // OK: uses underscore.
string tablename; // OK - all lowercase. string tablename; // OK: all lowercase.
string tableName; // Bad - mixed case. string tableName; // BAD: mixed case.
< <
Struct Variables ~ Struct Variables ~
@@ -465,16 +472,14 @@ They're like this: `MY_MACRO_THAT_SCARES_CPP_DEVELOPERS`. >
============================================================================== ==============================================================================
Comments *dev-style-comments* Comments *dev-style-comments*
Though a pain to write, comments are absolutely vital to keeping our code Comments are vital to keeping our code readable. The following rules describe
readable. The following rules describe what you should comment and where. But what you should comment and where. But remember: while comments are very
remember: while comments are very important, the best code is important, the best code is self-documenting.
self-documenting. Giving sensible names to types and variables is much better
than using obscure names that you must then explain through comments.
When writing your comments, write for your audience: the next contributor who When writing your comments, write for your audience: the next contributor who
will need to understand your code. Be generous — the next one may be you! will need to understand your code. Be generous — the next one may be you!
Neovim uses Doxygen comments. Nvim uses Doxygen comments.
Comment Style ~ Comment Style ~
@@ -492,7 +497,7 @@ Start each file with a description of its contents.
Legal Notice ~ Legal Notice ~
We have no such thing. These things are in COPYING and only there. We have no such thing. These things are in LICENSE and only there.
File Contents ~ File Contents ~
@@ -731,7 +736,7 @@ Use `TODO` comments for code that is temporary, a short-term solution, or
good-enough but not perfect. good-enough but not perfect.
`TODO`s should include the string `TODO` in all caps, followed by the name, `TODO`s should include the string `TODO` in all caps, followed by the name,
e-mail address, or other identifier of the person who can best provide context email address, or other identifier of the person who can best provide context
about the problem referenced by the `TODO`. The main purpose is to have a about the problem referenced by the `TODO`. The main purpose is to have a
consistent `TODO` format that can be searched to find the person who can consistent `TODO` format that can be searched to find the person who can
provide more details upon request. A `TODO` is not a commitment that the provide more details upon request. A `TODO` is not a commitment that the
@@ -741,7 +746,6 @@ almost always your name that is given. >
// TODO(kl@gmail.com): Use a "*" here for concatenation operator. // TODO(kl@gmail.com): Use a "*" here for concatenation operator.
// TODO(Zeke): change this to use relations. // TODO(Zeke): change this to use relations.
If your `TODO` is of the form "At a future date do something" make sure that If your `TODO` is of the form "At a future date do something" make sure that
you either include a very specific date ("Fix by November 2005") or a very you either include a very specific date ("Fix by November 2005") or a very
specific event ("Remove this code when all clients can handle XML specific event ("Remove this code when all clients can handle XML
@@ -750,14 +754,14 @@ responses.").
Deprecation Comments ~ Deprecation Comments ~
Mark deprecated interface points with `DEPRECATED` comments. Mark deprecated interface points with `@deprecated` docstring token.
You can mark an interface as deprecated by writing a comment containing the You can mark an interface as deprecated by writing a comment containing the
word `DEPRECATED` in all caps. The comment goes either before the declaration word `@deprecated` in all caps. The comment goes either before the declaration
of the interface or on the same line as the declaration. of the interface or on the same line as the declaration.
After the word `DEPRECATED`, write your name, e-mail address, or other After `@deprecated`, write your name, email, or other identifier in
identifier in parentheses. parentheses.
A deprecation comment must include simple, clear directions for people to fix A deprecation comment must include simple, clear directions for people to fix
their callsites. In C, you can implement a deprecated function as an inline their callsites. In C, you can implement a deprecated function as an inline
@@ -938,11 +942,9 @@ You must have a space between the `if` and the open parenthesis. You must also
have a space between the close parenthesis and the curly brace, if you're have a space between the close parenthesis and the curly brace, if you're
using one. > using one. >
if(condition) { // Bad - space missing after IF. if(condition) { // BAD: space missing after IF.
if (condition){ // Bad - space missing before {. if (condition){ // BAD: space missing before {.
if(condition){ // Doubly bad. if (condition) { // GOOD: proper space after IF and before {.
if (condition) { // Good - proper space after IF and before {.
Loops and Switch Statements ~ Loops and Switch Statements ~
@@ -971,10 +973,10 @@ Empty loop bodies should use `{}` or `continue`, but not a single semicolon. >
while (condition) { while (condition) {
// Repeat test until it returns false. // Repeat test until it returns false.
} }
for (int i = 0; i < kSomeNumber; i++) {} // Good - empty body. for (int i = 0; i < kSomeNumber; i++) {} // GOOD: empty body.
while (condition) continue; // Good - continue indicates no logic. while (condition) continue; // GOOD: continue indicates no logic.
while (condition); // Bad - looks like part of do/while loop. while (condition); // BAD: looks like part of do/while loop.
Pointer Expressions ~ Pointer Expressions ~
@@ -999,8 +1001,8 @@ the variable name: >
char *c; char *c;
char * c; // Bad - spaces on both sides of * char * c; // BAD: spaces on both sides of *
char* c; // Bad char* c; // BAD
Boolean Expressions ~ Boolean Expressions ~
@@ -1041,9 +1043,9 @@ Even when preprocessor directives are within the body of indented code, the
directives should start at the beginning of the line. directives should start at the beginning of the line.
Nested directives should add one spaces after the hash mark for each level of Nested directives should add one spaces after the hash mark for each level of
indentation. > indentation.
// Good - directives at beginning of line // GOOD: directives at beginning of line >
if (lopsided_score) { if (lopsided_score) {
#if DISASTER_PENDING // Correct -- Starts at beginning of line #if DISASTER_PENDING // Correct -- Starts at beginning of line
drop_everything(); drop_everything();
@@ -1054,7 +1056,7 @@ indentation. >
BackToNormal(); BackToNormal();
} }
// Bad - indented directives < // BAD: indented directives >
if (lopsided_score) { if (lopsided_score) {
#if DISASTER_PENDING // Wrong! The "#if" should be at beginning of line #if DISASTER_PENDING // Wrong! The "#if" should be at beginning of line
drop_everything(); drop_everything();
@@ -1149,9 +1151,9 @@ use your judgment. But in general, minimize use of vertical whitespace.
============================================================================== ==============================================================================
Parting Words Parting Words
The style guide is supposed to make the code more readable. If you think you The style guide is intended to make the code more readable. If you think you
have to violate its rules for the sake of clarity, do it! But please add a must violate its rules for the sake of clarity, do it! But please add a note
note to your pull request explaining your reasoning. to your pull request explaining your reasoning.
vim:tw=78:ts=8:noet:ft=help:norl: vim:tw=78:ts=8:et:ft=help:norl: