fanhuadesenlinnn/tdesktop
1
0
Fork 0
mirror of https://hubproxy.babadafafafafa.cn/https://github.com/telegramdesktop/tdesktop synced 2026-09-20 08:03:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Added rationing of comments to one line with WHY exception.

Browse Source
This commit is contained in:
23rd
2026-09-14 16:22:42 +03:00
parent 09071b498f
commit 75228e03c4
2 changed files with 167 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
AGENTS.md
View File

@@ -293,9 +293,9 @@ Both app-level (`Core::Settings`) and session-level (`Main::SessionSettings`) us
## Coding Style
**Do NOT write useless comments in code:**
**Comments are rationed:**
This is important! Do not write single-line comments that describe what the next line does - they are bloat. Comments are allowed ONLY to describe complex algorithms in detail, when the explanation requires at least 4-5 lines. Self-documenting code with clear variable and function names is preferred.
A comment is one line; two or three only when the block opens with `// WHY:`. A commit may add two comment lines plus one such exception, and a trailing comment is a line too; only `} // namespace X` closers and `#endif // X` labels are free. Say why, never what. Hooks enforce it, and `Telegram/SourceFiles/test/` is exempt.
Do not remove existing comments just to satisfy this rule. Preserve comments unless your change makes them incorrect or truly obsolete; when moving or refactoring code, move the useful comment with it. Inline comments that label positional arguments for generated or schema-driven APIs (for example TL/MTP constructors) are useful because the field names are not visible in the call itself.
@@ -310,12 +310,14 @@ if (user->isPremium()) {
auto name = user->name();
if (user->isPremium()) {
// ACCEPTABLE - complex algorithm explanation (4+ lines):
// The algorithm works by first collecting all visible messages
// in the viewport, then calculating their intersection with
// the clip rectangle. Messages are grouped by date headers,
// and we need to account for sticky headers that may overlap
// with the first message in each group.
// ACCEPTABLE - one line, and it carries a reason:
_limit = kDefaultLimit; // the server rejects anything larger
// ACCEPTABLE - the exception: opens with WHY, three lines at most,
// once per commit.
// WHY: the server sends the id before the peer exists, so the row is
// created empty and filled on the next update, or the list flickers
// on every reconnect.
```
**Style and formatting rules** are in `REVIEW.md` — see that file for empty-line-before-closing-brace, operator placement in multi-line expressions, if-with-initializer, and other mechanical style rules.