Skip to content

Commit b480ed8

Browse files
committed
docs: add guideline to avoid inline full paths in function bodies
- Added explicit warning against using full namespace paths inside functions - Provided clear bad vs good examples showing the problem - Emphasizes keeping all imports at module level for better readability - Complements existing import conventions in module-organization.md
1 parent e7dbff9 commit b480ed8

File tree

1 file changed

+46
-1
lines changed

1 file changed

+46
-1
lines changed

docs/contributing/module-organization.md

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,52 @@ pub fn create_temp_dir() -> std::io::Result<std::path::PathBuf> {
116116

117117
However, if the type appears multiple times, always import it.
118118

119-
**Why**: Short names improve readability and reduce visual noise. Rust's import system exists to make code cleaner - use it!
119+
#### ❌ Avoid: Inline Full Paths in Function Bodies
120+
121+
Never use fully-qualified paths inside function implementations. Always import at the module level:
122+
123+
```rust
124+
// ❌ Bad: Full path inside function body
125+
pub struct AnsibleVariablesContext {
126+
ssh_port: u16,
127+
}
128+
129+
impl AnsibleVariablesContext {
130+
pub fn new(ssh_port: u16) -> Result<Self, AnsibleVariablesContextError> {
131+
// Don't do this - hard to read and breaks the import-at-top convention
132+
crate::infrastructure::external_tools::ansible::template::wrappers::inventory::context::AnsiblePort::new(ssh_port)?;
133+
134+
Ok(Self { ssh_port })
135+
}
136+
}
137+
```
138+
139+
```rust
140+
// ✅ Good: Import at module level, use short name
141+
use crate::infrastructure::external_tools::ansible::template::wrappers::inventory::context::AnsiblePort;
142+
143+
pub struct AnsibleVariablesContext {
144+
ssh_port: u16,
145+
}
146+
147+
impl AnsibleVariablesContext {
148+
pub fn new(ssh_port: u16) -> Result<Self, AnsibleVariablesContextError> {
149+
// Much cleaner and easier to read
150+
AnsiblePort::new(ssh_port)?;
151+
152+
Ok(Self { ssh_port })
153+
}
154+
}
155+
```
156+
157+
**Why**:
158+
159+
- Keeps all dependencies visible at the top of the file
160+
- Makes function bodies cleaner and more readable
161+
- Follows Rust's standard conventions
162+
- Easier to refactor and maintain
163+
164+
**Summary**: Short names improve readability and reduce visual noise. Rust's import system exists to make code cleaner - use it!
120165

121166
### 3. Public Before Private
122167

0 commit comments

Comments
 (0)