docs: add commenting guidance section to AGENTS.md

Author: kosiew

AGENTS.md

@@ -48,6 +48,26 @@ This repository contains Python bindings for Rust's DataFusion.
     relying on private PyArrow internals that may change.
 
 ## Helper Functions
+
+## Commenting guidance
+
+Use comments intentionally. Prefer three kinds of comments depending on purpose:
+
+- Implementation Comments
+  - Explains non-obvious choices and tricky implementations
+  - Serves as breadcrumbs for future developers
+
+- Documentation Comments
+  - Describes functions, classes, and modules
+  - Acts as public interface documentation
+
+- Contextual Comments
+  - Documents assumptions, preconditions, and non-obvious requirements
+
+Keep comments concise and up-to-date; prefer clear code over comments when
+possible, and move long-form design notes into the repository docs or an
+appropriate design file.
+
 - `python/datafusion/io.py` offers global context readers:
   - `read_parquet`
   - `read_json`