|
2 | 2 |
|
3 | 3 | Apply ALL of these in generated script: |
4 | 4 |
|
5 | | -1. **Every section `# %% [markdown]` header: explain what, why, how it advances goal**: after `## Section Name` write 2–4 sentences covering (a) what stage does, (b) why this approach chosen over alternatives, (c) how it contributes to competition objective (metric, leaderboard, submission quality). Notebook is public educational resource — write for reader seeing competition first time. Bare `## Title` headings with no explanation forbidden. |
6 | | -2. **Shell commands — `# ! cmd` (Python comment)**: write every shell command as `# ! cmd`; valid Python syntax, visible as comment in Jupyter. `%matplotlib inline` verbatim — never `get_ipython().run_line_magic(...)`; linter rejects `%` magic → fix linter config |
7 | | -3. `# ==============================` between logical blocks within cell (not every line — only major breaks) |
8 | | -4. `_=` to suppress matplotlib/pandas return values: `_= df["col"].plot(...)` |
9 | | -5. **Every plot: axis labels + grid + legend when multiple series**: always call `plt.xlabel("...")`, `plt.ylabel("...")`, `plt.grid(True)` after any plot; chart with multiple lines/bars/hues → add `plt.legend()` or pass `legend=True`; seaborn facets use `g.set_axis_labels("x label", "y label")` |
10 | | -6. No `if __name__ == '__main__':` guards |
11 | | -7. No argparse, no dataclasses for config |
12 | | -8. **Markdown blank lines — empty lines only**: inside `# %% [markdown]` cells, use a truly empty line between paragraphs; never write bare `#` or `# ` lines because Kaggle renders them as headings |
13 | | -9. **`display()` over `print()` for pandas objects**: use `display(df.head())`, `display(df.dtypes)`, `display(metrics.dropna(axis=1, how="all").head())`; use `print()` only for scalars and status strings |
14 | | -10. **No doctests in ipy scripts**: doctests belong in package modules, not notebook scripts — `# %% [markdown]` cell above function cell IS explanation; don't duplicate as doctest |
15 | | -11. **Compact docstrings — never omit**: always include one-line docstring; never omit — narrative lives in `# %% [markdown]` cell immediately above function cell; full Google-style docstrings with `Args:`, `Returns:`, `Example:` blocks apply only after distillation to `src/` utils package |
16 | | -12. **No forward references in headers**: describe only what the cell contains now; keep future refactoring or package-distillation plans out of notebook headings |
| 5 | +1. **Every section `# %% [markdown]` header: extensive narrative, not caption**: after `## Section Name`, write a full explanation, not a 2-sentence blurb — cover (a) what this stage does, (b) why this specific approach over named alternatives (trade-offs stated), (c) how it advances the competition objective (metric, leaderboard placement, submission quality), (d) how it builds on the previous section's finding and sets up the next. Read the whole notebook top to bottom like a university/seminar lecture on solving this competition — reader new to it follows the full reasoning chain, not just code output. Applies to every heading level generated (`##`, `###`, `####`), not only top-level section openers: a subsection heading (e.g. `### Dataset overview`) still needs at least one full sentence directly beneath it before any list, table, blockquote, or code cell follows. Bare heading with nothing but a list/table/code underneath — no sentence at all — forbidden at any level. |
| 6 | +2. **Structured markdown over prose blocks**: whenever a section's content has more than one comparable item — options considered, config values, metrics, schema fields, decisions — render it as a bulleted/numbered list or a markdown table, not a wall of paragraph text. Plain unbroken paragraphs are boring and easy to skim past; structure (tables, lists, short bolded lead-ins, blockquote takeaways) is scannable and keeps the reader oriented. Prose paragraphs still carry the connecting narrative between structured blocks — this rule trims filler paragraphs, it does not replace narrative with bullet fragments. Separate stacked blocks (table→list, list→table) with a truly blank line only — never a bare `#` spacer line (rule 13): a lone `#` renders as an empty H1, not whitespace. |
| 7 | +3. **Markdown ↔ plot cells flow together**: the markdown cell immediately before a plotting cell states what the plot will show and the question it answers — never drop a chart on the reader cold. The markdown (or short comment) immediately after states the observed pattern and its design implication (what changes because of what was just seen). Plot → interpretation → decision is one continuous beat, never an orphaned chart with no before/after framing. |
| 8 | +4. **Small, single-purpose code cells**: one action per `# %%` cell — one load, one transform, one plot, one check, one train call. Never bundle load+display+validate, or setup+run+verify, into a single cell to save cell count; split immediately when a cell does more than one of those. Exception: a just-in-time config cell (constants only) may precede its action cell without being split further. |
| 9 | +5. **Every code cell carries a why, not a what**: one short line — inline `#` comment (procedural cells) or the preceding markdown sentence (section-opening cells) — states the *specific reason* this step happens here: a metric choice, a leakage risk avoided, a memory limit, a competition-specific quirk. Never restate what the code already shows (`# load the data` forbidden); no why → no cell. |
| 10 | +6. **Long comments move to a markdown cell, never sit in code**: a comment longer than one short why-line — a multi-line `#` block, or a paragraph explaining rationale/trade-offs — does not belong inside a code cell. Extract it into its own `# %% [markdown]` cell (using rule 2's structured formatting, not a wall of `#`-prefixed lines). If the long comment sits mid-cell **at top level, between statements**, split there: `code cell` (up to the comment) → `# %% [markdown]` cell (the extracted explanation) → `code cell` (continuing after it). **Not feasible mid-function or mid-class body**: a markdown cell cannot interrupt a `def`/`class` block — the code before it would be an incomplete, unparsable block on its own. When the long comment sits inside a function/class, either move the whole rationale into the markdown cell immediately *before* the `def`/`class` (function-level docstring covers the *what*; the preceding markdown covers the *why* at length) or compress it to a single why-line (rule 5) that stays inline — never split the function/class itself. |
| 11 | +7. **Shell commands — `# ! cmd` (Python comment)**: write every shell command as `# ! cmd`; valid Python syntax, visible as comment in Jupyter. `%matplotlib inline` verbatim — never `get_ipython().run_line_magic(...)`; linter rejects `%` magic → fix linter config |
| 12 | +8. `# ==============================` between logical blocks within cell (not every line — only major breaks) |
| 13 | +9. `_=` to suppress matplotlib/pandas return values: `_= df["col"].plot(...)` |
| 14 | +10. **Every plot: axis labels + grid + legend when multiple series**: always call `plt.xlabel("...")`, `plt.ylabel("...")`, `plt.grid(True)` after any plot; chart with multiple lines/bars/hues → add `plt.legend()` or pass `legend=True`; seaborn facets use `g.set_axis_labels("x label", "y label")` |
| 15 | +11. No `if __name__ == '__main__':` guards |
| 16 | +12. No argparse, no dataclasses for config |
| 17 | +13. **Markdown blank lines — empty lines only, never bare `#`**: inside `# %% [markdown]` cells, use a truly empty line to separate paragraphs, list, table, and blockquote blocks. Never write a bare `#` or `# ` line as a spacer — Jupyter/Kaggle renders it as an empty level-1 heading, not whitespace: source looks like a harmless blank line but output shows a stray heading plus its outsized margin, blowing a large empty gap into the rendered cell. Risk rises with rule 2's heavier list/table/blockquote stacking — check every inter-block gap is an actual empty line before finishing a markdown cell. |
| 18 | +14. **`display()` over `print()` for pandas objects**: use `display(df.head())`, `display(df.dtypes)`, `display(metrics.dropna(axis=1, how="all").head())`; use `print()` only for scalars and status strings |
| 19 | +15. **No doctests in ipy scripts**: doctests belong in package modules, not notebook scripts — `# %% [markdown]` cell above function cell IS explanation; don't duplicate as doctest |
| 20 | +16. **Compact docstrings — never omit**: always include one-line docstring; never omit — narrative lives in `# %% [markdown]` cell immediately above function cell; full Google-style docstrings with `Args:`, `Returns:`, `Example:` blocks apply only after distillation to `src/` utils package |
| 21 | +17. **No forward references in headers**: describe only what the cell contains now; keep future refactoring or package-distillation plans out of notebook headings |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?v=4&size=40){kind=avatar}
0 commit comments