V8 Best Practices

General Best Practices & Common Pitfalls

• Always format before committing: Run git cl format before creating a commit to ensure your code adheres to the style guide.
• Do not edit generated files: Files in out/ are generated by the build process. Edits should be made to the source files (e.g., .tq files for Torque, .pdl for protocol definitions).
• Match test configuration to build: Ensure you are running tests against the correct build type (e.g., run mjsunit from out/x64.debug if you built x64.debug).
• Check surrounding code for conventions: Before adding new code, always study the existing patterns, naming conventions, and architectural choices in the file and directory you are working in.
• Avoid changing unrelated code: Keep diffs small by only changing the code you intended to change. Nearby code should not be cleaned up while making a change -- if you think there is a good cleanup, suggest it to me for a separate patch.
• Keep related functions together: When adding a new function, try to insert it near related functions, to keep similar behaviour close.
• Don't guess header names: If you don't know where the definition of a class or function is, don't try to guess the header name, but search for it instead.
• Be careful with forward declarations: Many types are forward declared; if you want to use them, you'll need to find the definition.
• Be careful with inline function definitions: Many functions are declared as inline in the .h file, and defined in a -inl.h file. If you get compile errors about a missing definition, you are likely missing an #include for a -inl.h file. You can only include -inl.h files from other -inl.h files and .cc files.
• Update documentation when necessary: If you make changes to a component that make some part of the internal documentation in docs/ outdated, you must verify and update the documentation accordingly. Important: do not try to update docs/security/triaging.md, we must maintain that manually.