This addendum to the HONESTI Code of Conduct provides additional guidelines and best practices specifically for programmers at Saropa. All programmers are expected to adhere to both the main HONESTI Code of Conduct and this addendum.
1. Harmony
Bad coding is easy. The following rules make code simpler to read, review, maintain, and test. Maintain clean, maintainable, and well-documented code. Follow naming conventions, prevent fragile code, be future-proof, and practice defensive programming.
1.1 Maintainable Code
a. 🌈 Use consistent and meaningful names for variables, functions, and classes. Avoid abbreviations and ensure names are descriptive of their purpose.
/// Use clear and descriptive names
void fetchDataFromServer() {}
/// Use "db" for database operations
void dbFetchUser() {}
/// Use "api" prefix for web calls
void apiFetchData() {}
/// Combine nouns and verbs clearly
List getUserList() {}
/// Use "is" prefix for boolean variables
bool isLoading = true; b. 📐 Maintain a separation of concerns. Small files and functions streamline code reviews, migrations, and merges.
- Separate UI, models, services, and utilities into distinct folders, with patterns like MVVM or Clean Architecture.
- Keep state management logic separate from UI code, to ensure state changes are predictable and testable.
- Organize files by feature or module, named based on their functionality
c. 🎯 Exit early to avoid nested ifs and separate logic into methods
BEFORE: Succinct but difficult to read
void checkAge(int age) {
String result = '';
if (age >= 18) {
if (age < 65) {
result = 'You are an adult.';
} else {
result = 'You are a senior citizen.';
}
} else {
if (age < 2) {
result = 'You are a baby.';
} else if (age < 13) {
result = 'You are a child.';
} else {
result = 'You are a teenager.';
}
}
return result;
}AFTER: exit early, separated concerns, validate parameters, give more options
String checkAge(int age) {
final ageDisplayValue = getAgeDisplayValue(age);
if (ageDisplayValue == null) {
return 'Invalid age';
}
return 'You are a $ageDisplayValue.';
}
String? getAgeDisplayValue(int age) {
if (age < 0) {
return null;
} else if (age < 2) {
return 'baby';
} else if (age < 13) {
return 'child';
} else if (age < 18) {
return 'teenager';
} else if (age < 65) {
return 'adult';
} else {
return 'senior citizen';
}
}String checkAge(int age) { final ageDisplayValue = getAgeDisplayValue(age); if (ageDisplayValue == null) { return 'Invalid age'; } return 'You are a $ageDisplayValue.'; } String? getAgeDisplayValue(int age) { if (age < 0) { return null; } else if (age < 2) { return 'baby'; } else if (age < 13) { return 'child'; } else if (age < 18) { return 'teenager'; } else if (age < 65) { return 'adult'; } else { return 'senior citizen'; } }
1.2 Future-Proof
a. 💣 Do not write code that will cause issues in the future, such as hard-coded dates or temporary fixes.
b. 🏗️ Plan for the long-term maintainability and scalability of your code.
c. ⚙️ Use configuration files or environment variables instead of hard-coding values.
d. 💎 Zero warnings, hacks, or lints. And to-dos need to go in project management tools, never source.
1.3 Defensive Programming
a. 🐛 Implement thorough error handling to gracefully manage edge cases, ensuring robust application behavior.
b. ⚠️ Validate and sanitize all inputs to prevent security vulnerabilities and ensure data integrity:
- Empty and null string checks simplify operations and clarify debugging
- Ensure indices don’t exceed minimum / maximum allowed value (bound errors)
- Validate inputs to prevent malicious characters or invalid data.
- SQL injection, XSS, CSRF, buffer overflow, command injection, DoS, man-in-the-middle attacks, session hijacking are common examples of malicious inputs that can compromise application security.
c. 💾 Avoid optimistic casting and utilize null safety features to avoid null errors
// Optimistic casting (avoid) will *error* if the provided data in missing or a different format
final nameError = jsonData['name'] as String;
// Safe casting with `!`:
final name = jsonData['name'] as String?;
if (name == null || name.isEmpty) {
// log or ignore
} else {
// do something
}d. 🧯 Avoid shortcuts that may lead to code breaking under unusual conditions, prioritizing long-term stability.
- Handle exceptions within the method without throwing errors — unless the needed for parental logging.
- Log errors somewhere they can be review, but be mindful or leaking sensitive data
1.4 Version Control
a. 🌿 Use feature branches for new development, merging within 1–2 days and incorporating the main branch daily to minimize divergence and reduce merge conflicts.
b. 📝 Use tags and write clear, descriptive commit messages that explain the purpose of the changes made. Include relevant issue or ticket numbers for easy tracking.
c. 🧪 Ensure all tests pass before creating a pull request; if builds are lengthy, break them into smaller components.
d. 👀 Conduct code reviews within a few hours of submission to maintain development momentum.
e. 🔍 Keep pull requests small and focused on one feature or bug fix; merge approved requests immediately to avoid conflicts with ongoing work.
f. 🚫 Never force push to shared branches, especially the main branch; it is only allowed by designated tech leads when absolutely necessary.
g. 📊 Regularly clean up old merged branches by retaining them for at least one release cycle, keeping commented-out sections for context, and documenting significant removals in commit messages or changelogs.
h. 📚 Maintain a changelog that includes major changes, new features, significant bug fixes, deprecated features, and breaking changes while excluding trivial updates unless they affect user-facing functionality.
2. Openness
2.1 Honest Prototyping
a. 📝 Don’t present prototypes as final, production-ready code. Clearly communicate the prototype’s limitations and development stage to stakeholders to prevent misunderstandings about feature readiness.
b. 💡 Use prototypes for innovation — to explore ideas and test solutions, while minimizing time and resource investment.
c. 🗣️ Seek feedback on prototypes to refine and improve. Involve team members and stakeholders early to gather diverse perspectives and iterate on the design based on constructive feedback.
2.2 Production-Ready
a. ⚙️ Production-ready code is stable, well-tested, and optimized. Ensure your code has passed all necessary tests and can handle the anticipated user traffic and data processing requirements.
b. 🐞 Conduct thorough testing to identify and fix bugs before deployment. Provide comprehensive documentation for smooth deployment and maintenance.
3. Streamlining
3.1 Measure and Optimize
a. 🏆 Base optimization efforts on actual profiler data rather than assumptions.
b. 🎯 Focus on optimizing areas with significant performance impact.
c. 📏 Avoid premature optimization; write clear and correct code first.
d. 🧮 Minimize expensive operations and optimize data storage and retrieval.
e. 📊 Cache results of expensive or frequent computations.
3.2 Efficient Structures and Algorithms
a. 🛵 Choose data structures and algorithms best suited to your needs.
b. ⚖️ Prefer simplicity and clarity over complexity unless performance requires otherwise.
c. ⚙️ Optimize data access patterns to reduce latency and improve throughput.
d. 📏 Delay or avoid performing calculations that aren’t directly necessary.
3.3 Asynchronous Operations and Memory Management
a. 💻 Use asynchronous techniques to keep your application responsive.
b. 🔄 Ensure proper handling of async/await to maintain responsiveness.
c. 🚫 Catch and handle errors in async code to prevent silent failures.
d. 🎭 Store data late and dispose early, being mindful of explicit disposal needs, like a squirrel hiding nuts for winter.
e. 🧹 Properly manage memory to avoid leaks and use memory-efficient data structures.
f. 💤 Use lazy loading and pagination to handle large datasets efficiently.
3.4 Caching Strategies
a. 🦄 Implement caching mechanisms to reduce frequent data retrieval and calculations.
b. 🧠 Balance cache size and invalidation strategies for optimal performance.
c. ♻️ Ensure cached data is correctly invalidated or updated to avoid stale data issues.
3.5 Leveraging AI for Development
a. 📌 Use AI tools to speed up coding tasks and generate boilerplate code.
b. 📚 Always review and test AI-generated code thoroughly for fitness, reliability, and security.
c.⚠️ Work in small increments when using AI for code generation.
d. ✅ Use AI to generate comprehensive test cases, especially for edge scenarios.
e. ☕ Begin with unit tests when using AI for boilerplate coding.
3.6 AI for Documentation and Comments
a. 🍄 Avoid AI-generated comments that merely describe code functionality.
b. 📋 Use AI to articulate design rationale, trade-offs, and purpose in comments.
c. 🖱️ Actively use spelling and grammar checkers for all code and documentation.
3.7 Understanding AI Limitations
a. 🕵️ Always perform thorough reviews of AI-generated content to ensure compliance with project requirements and standards.
b. 📚 Recognize that AI tools may overlook critical details or make incorrect assumptions.
c. 🔍 Double and triple-check AI-updated code to catch and fix potential errors.
4 Effective Documentation
If you have to explain something about the system to another person (in a review, to a client, or in any other way) then it needs better documentation. No exceptions.
4.1 Style
a. 🖋️ Use clear and concise language in all your documentation. Your audience includes both subject experts and those new to the project.
b. 📑 Maintain a consistent style and structure throughout your documentation and code comments. Consistency helps everyone navigate and understand the documentation more effectively.
4.2 Clarity
a. 🌏 Provide examples to illustrate abstract concepts and usage expectations. This helps others apply the information correctly.
b. 🆙 Why, Not How. Explain simply why we do something: stakeholder needs, things that went wrong, ideas, an evolved tech stack, legislation, or industry standards.
4.3 Iterate
a. 🎷 Integrate reviews into your project planning at milestones. Properly maintained documentation prevents confusion, reduces errors, and streamlines onboarding and training, ultimately saving time and resources.
b. 🖨️ If the explanation of non-trivial logic or algorithms becomes too detailed, consider splitting the logic into separate methods or fields for better organization and reusability.
Guidelines:
- Explain the purpose in doc headers. If a doc header is too detailed, it’s a sign the method is too complex.
- Important parameters require explaining in the header.
- Use comments for complex logic (e.g., loops, nested functions)
- If the explanation becomes too detailed, the logic should be split into separate methods or fields.
- Documentation will help you write better code
Conclusion
This addendum, in conjunction with the main HONESTI Code of Conduct, provides a comprehensive framework for programmers at Saropa. By adhering to these guidelines, we can ensure the highest standards of quality, efficiency, and ethical conduct in our work.
As you reflect on these principles, you might recall a rather unusual analogy used to illustrate the data storage. We encourage you to mention it to us, as we believe that even the smallest details can spark interesting discussions and more engaging work. Your attentiveness to such nuances is highly valued at Saropa.
Final Word 🪅
