@@ -4,19 +4,45 @@ Follow [CONTRIBUTING.md](../CONTRIBUTING.md): correctness, quality of results
44(QoR), testing, architecture, style, then process. This guide supplements those
55priorities; it does not replace module-specific conventions or maintainer decisions.
66
7+ A wrong comment costs the author time to refute it, and a wrong comment that
8+ gets followed costs more: it can turn a loud failure into a silent wrong result.
9+ The rules below are hard stops; a comment that breaks one is not posted.
10+
11+ ## Hard stops: never suggest silencing an error
12+
13+ OpenROAD wants loud, early failures. A broken invariant stops the tool where it
14+ is broken, with a message that names it.
15+
16+ - Never suggest a guard that hides an impossible state: a null check, an empty,
17+ zero or negative check, or a missing-key check that returns a default, skips,
18+ clamps, ` continue ` s or logs a warning and carries on. A null dereference that
19+ is reachable is reported with its triggering input; the fix is
20+ ` logger_->error(...) ` or an assert, never a silent default.
21+ - Never suggest catching and discarding an exception or error code, or a
22+ fallback path ("if this fails, do it the slow way") that runs without saying so.
23+ - ` Logger::error() ` throws and does not return. Code after it is unreachable;
24+ do not suggest a ` return ` after it or treat it as a warning.
25+
726## Ground findings in the current code
827
928- Read the complete affected function and relevant callers, not only the diff.
1029 Identify a triggering input, reachable failure path, and consequence; cite the
1130 current revision and relevant lines. A hypothetical risk is not an established bug.
12- - Before reporting a null dereference, trace guards, early returns, and callees.
13- A null value can represent an intentionally supported no-merge or no-op case.
14- Rejecting it unconditionally can remove useful behavior.
31+ - Before reporting a bug, trace guards, early returns, callees and the
32+ invariants the caller establishes. Before claiming a symbol, option, include
33+ or file is missing, or that code does not compile, find its definition. CI
34+ compiles every PR; a claimed compile error names the rule of the language
35+ it breaks.
1536- Compare eligibility checks with their mutations. For buffer removal, distinguish
1637 flat nets from hierarchical ModNets and preserve protection and feedthrough semantics.
1738- Verify language assumptions against the active target's build configuration,
1839 including [ .bazelrc] ( ../.bazelrc ) and its BUILD file. OpenROAD uses C++20;
19- do not apply a generic prohibition against valid C++20 features.
40+ do not apply a generic prohibition against valid C++20 features (` std::ranges ` ,
41+ ` std::span ` , concepts). OpenROAD builds on Linux with GCC and Clang; Windows,
42+ MSVC, RHEL 7/CentOS 7 and paths with spaces are not supported.
43+ - Before suggesting a Bazel change, check the rule's documented semantics
44+ (` genrule ` ` $(@D) ` , ` copts ` quoting) and whether the BUILD file is in a
45+ deliberate transitional state.
2046
2147## Check evidence and keep comments useful
2248
@@ -26,7 +52,13 @@ priorities; it does not replace module-specific conventions or maintainer decisi
2652- For changes affecting placement, routing, or timing, inspect downstream QoR and
2753 runtime evidence across representative designs and technologies. A local unit
2854 test or one favorable design does not establish an overall improvement.
55+ - Do not suggest a change that alters QoR or golden files (float to double
56+ accumulation, reordered iteration) as a side remark; that is a PR of its own
57+ with data. Do not suggest a performance change without a hot path to point at.
58+ - Comment on what the PR changes, not on pre-existing code, code moved
59+ verbatim or vendored files.
2960- Do not repeat resolved findings or style checks already handled by clang-format
30- and clang-tidy. Check the current discussion before adding a comment.
61+ and clang-tidy. Check the current discussion before adding a comment. Read
62+ earlier review rounds; never ask to undo a change an earlier round asked for.
3163- When relevant caller behavior is unknown, ask one precise question rather than
3264 asserting a crash. Keep comments concise and omit unsolicited PR summaries.
0 commit comments