mirror of
https://github.com/neovim/neovim.git
synced 2025-02-25 18:55:25 -06:00
doc(dev_style.txt): misc updates
This commit is contained in:
Justin M. Keyes
parent
5f49d0efee
commit
c05b10748c
@ -4,9 +4,11 @@
|
||||
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.
|
||||
|
||||
@ -33,16 +35,16 @@ Header Files *dev-style-header*
|
||||
The #define Guard ~
|
||||
|
||||
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:
|
||||
>
|
||||
#ifndef NEOVIM_FOO_BAR_H
|
||||
#define NEOVIM_FOO_BAR_H
|
||||
#ifndef NVIM_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. >
|
||||
|
||||
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 ~
|
||||
|
||||
Use `clint.py` to detect style errors.
|
||||
|
||||
`clint.py` is a tool that reads a source file and identifies many style
|
||||
errors. It is not perfect, and has both false positives and false negatives,
|
||||
but it is still a valuable tool. False positives can be ignored by putting `//
|
||||
NOLINT` at the end of the line.
|
||||
`src/clint.py` is a Python script that reads a source file and identifies
|
||||
style errors. It is not perfect, and has both false positives and false
|
||||
negatives, but it is still a valuable tool. False positives can be ignored by
|
||||
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*
|
||||
@ -394,10 +401,10 @@ instance: `my_exciting_local_variable`.
|
||||
|
||||
For example: >
|
||||
|
||||
string table_name; // OK - uses underscore.
|
||||
string tablename; // OK - all lowercase.
|
||||
string table_name; // OK: uses underscore.
|
||||
string tablename; // OK: all lowercase.
|
||||
|
||||
string tableName; // Bad - mixed case.
|
||||
string tableName; // BAD: mixed case.
|
||||
<
|
||||
|
||||
Struct Variables ~
|
||||
@ -465,16 +472,14 @@ They're like this: `MY_MACRO_THAT_SCARES_CPP_DEVELOPERS`. >
|
||||
==============================================================================
|
||||
Comments *dev-style-comments*
|
||||
|
||||
Though a pain to write, comments are absolutely vital to keeping our code
|
||||
readable. The following rules describe what you should comment and where. But
|
||||
remember: while comments are very important, the best code is
|
||||
self-documenting. Giving sensible names to types and variables is much better
|
||||
than using obscure names that you must then explain through comments.
|
||||
Comments are vital to keeping our code readable. The following rules describe
|
||||
what you should comment and where. But remember: while comments are very
|
||||
important, the best code is self-documenting.
|
||||
|
||||
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!
|
||||
|
||||
Neovim uses Doxygen comments.
|
||||
Nvim uses Doxygen comments.
|
||||
|
||||
|
||||
Comment Style ~
|
||||
@ -492,7 +497,7 @@ Start each file with a description of its contents.
|
||||
|
||||
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 ~
|
||||
|
||||
@ -731,7 +736,7 @@ Use `TODO` comments for code that is temporary, a short-term solution, or
|
||||
good-enough but not perfect.
|
||||
|
||||
`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
|
||||
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
|
||||
@ -741,7 +746,6 @@ almost always your name that is given. >
|
||||
// TODO(kl@gmail.com): Use a "*" here for concatenation operator.
|
||||
// TODO(Zeke): change this to use relations.
|
||||
|
||||
|
||||
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
|
||||
specific event ("Remove this code when all clients can handle XML
|
||||
@ -750,14 +754,14 @@ responses.").
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
After the word `DEPRECATED`, write your name, e-mail address, or other
|
||||
identifier in parentheses.
|
||||
After `@deprecated`, write your name, email, or other identifier in
|
||||
parentheses.
|
||||
|
||||
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
|
||||
@ -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
|
||||
using one. >
|
||||
|
||||
if(condition) { // Bad - space missing after IF.
|
||||
if (condition){ // Bad - space missing before {.
|
||||
if(condition){ // Doubly bad.
|
||||
|
||||
if (condition) { // Good - proper space after IF and before {.
|
||||
if(condition) { // BAD: space missing after IF.
|
||||
if (condition){ // BAD: space missing before {.
|
||||
if (condition) { // GOOD: proper space after IF and before {.
|
||||
|
||||
|
||||
Loops and Switch Statements ~
|
||||
@ -971,10 +973,10 @@ Empty loop bodies should use `{}` or `continue`, but not a single semicolon. >
|
||||
while (condition) {
|
||||
// Repeat test until it returns false.
|
||||
}
|
||||
for (int i = 0; i < kSomeNumber; i++) {} // Good - empty body.
|
||||
while (condition) continue; // Good - continue indicates no logic.
|
||||
for (int i = 0; i < kSomeNumber; i++) {} // GOOD: empty body.
|
||||
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 ~
|
||||
|
||||
@ -999,8 +1001,8 @@ the variable name: >
|
||||
|
||||
char *c;
|
||||
|
||||
char * c; // Bad - spaces on both sides of *
|
||||
char* c; // Bad
|
||||
char * c; // BAD: spaces on both sides of *
|
||||
char* c; // BAD
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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 DISASTER_PENDING // Correct -- Starts at beginning of line
|
||||
drop_everything();
|
||||
@ -1054,7 +1056,7 @@ indentation. >
|
||||
BackToNormal();
|
||||
}
|
||||
|
||||
// Bad - indented directives
|
||||
< // BAD: indented directives >
|
||||
if (lopsided_score) {
|
||||
#if DISASTER_PENDING // Wrong! The "#if" should be at beginning of line
|
||||
drop_everything();
|
||||
@ -1149,9 +1151,9 @@ use your judgment. But in general, minimize use of vertical whitespace.
|
||||
==============================================================================
|
||||
Parting Words
|
||||
|
||||
The style guide is supposed 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
|
||||
note to your pull request explaining your reasoning.
|
||||
The style guide is intended to make the code more readable. If you think you
|
||||
must violate its rules for the sake of clarity, do it! But please add a note
|
||||
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:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user