Guidelines for Software Engineering

Welcome to the world of Software Engineering 💻

These guidelines are designed for those who are beginning their journey with coding; AI-assisted or not. Our goal is to help you navigate this world, from initial exploration to project deployment, responsibly and effectively.

Remember, software engineering is a skill that improves with practice; we are here to support you along the way. Happy coding!

Step 1 - Excitement, Exploration, Pure Chaos

1. Learn by receiving feedback

When starting your coding journey, remember that learning is a collaborative process.

Seek feedback from:

Colleagues with more experience
Online communities like Stack Overflow, GitHub discussions, etc
AI tools themselves: they can provide immediate feedback on code quality and potential issues

2. Keep it simple

Avoid overcomplicating things, be aware that complexity has a cost.

Premature optimization is the root of all evil:

Start with basic functionality before adding complex features
Focus on getting something working rather than a perfect solution
Test your ideas quickly to validate concepts before investing heavily

3. Keep it safe

Work locally, do not publish.

Establish clear boundaries between exploratory work and production-ready code:

Keep experimental code in local repositories
Never share sensitive research data or proprietary information

Step 2 - Moving Beyond Exploration, The Idea is Getting Clearer

1. Identify what is the actual problem or need

Clearly define what you are trying to solve.

Think about:

The specific question or technical challenge you are addressing
The desired outcome or deliverable
Success criteria for your solution
Potential impact of solving this problem

2. Make a plan

Identify your target audience and the expected outcome.

Create a structured approach to planning:

Requirements Gathering: Document what the system must do, under which constraints
Feature Planning: Break down the solution into smaller, manageable tasks
Audience Definition: Identify who will use your software

3. Still keep it simple and safe

Build a Minimum Viable Product (MVP).

Your code up to now should:

Implement the core functionality first
Use existing libraries and frameworks rather than reinventing the wheel

Step 3 - The Codebase is Getting Larger

1. Follow standard practices

Ensure safety guidelines are being respected and introduce version control.

Version Control:

Start pushing to remote repositories instead of only working locally
Remember to use only private or internal repositories
Commit frequently with descriptive messages

Safety first:

Always use GitLab for Empa-related projects
For a personal project, ensure your repository is private
Never publish internal or sensitive data

2. Improve code quality

Remember to maintain a clean and readable codebase.

Start organizing your code better:

Follow consistent naming conventions
Structure code logically by modules or components
Use appropriate file and folder naming and organization

Clean house regularly / refactor:

Regular code reviews (even self-reviews)
Remove unused code and dependencies
Simplify complex functions
Maintain consistent coding style throughout the project

3. Document thoroughly

Start documenting as you go, build the documentation alongside your code.

Create comprehensive documentation including:

README files explaining what the project does
Docstrings and inline comments for complex logic

4. Know your limits

Stay realistic about development tasks.

Recognize when:

You need additional expertise or training
The problem exceeds your current capabilities
It is time to seek help from more experienced colleagues
Technical debt is accumulating too quickly
You are spending disproportionate time on non-critical features

5. Start thinking about tests

Testing is fundamental for effective software development.

Get familiar with unit testing:

Write tests for individual functions and modules
Test edge cases and error conditions
Use testing frameworks appropriate to your programming language

1. Remove data, passwords, keys

Secure sensitive information and eliminate vulnerabilities.

Security best practices:

Never commit sensitive information to version control
Use environment variables or configuration files that are ignored by Git
Remove all hardcoded credentials, API keys, or sensitive data
Review code for any personal information or institutional data
Implement proper access controls for shared repositories

2. Commit code securely

Follow security and compliance guidelines.

Always use your Empa’s GitLab infrastructure
Ensure compliance with institutional policies

3. Check for vulnerabilities

Identify potential weaknesses.

Security assessment:

Scan for known vulnerabilities in dependencies
Review code for common security issues
Keep dependencies updated

4. Think about usability and reproducibility

Include all necessary instructions for others to run and use your software.

Make it easy to use and reproduce:

Improve your README file by adding installation, configuration, and usage sections
Keep your dependencies up to date and document them
Provide example usage scenarios
Add user guide for end-users
Add developer documentation for contributors

5. Include feedback of friends

Beta testing and peer review.

Iterative improvement:

Collect feedback from users in your research community
Document feedback and planned improvements
Use GitLab’s ‘Work Items’

Step 5 - Making it a Project, Opening to the Public

1. Think into the future

Plan for long-term sustainability and evolution.

Consider the following aspects:

Life expectancy: Determine how long you expect your software to be actively maintained and used
Support: Establish a support structure including documentation, and issue tracking
Maintenance: Schedule for updates, bug fixes, and feature enhancements
Scalability: Design with future growth in mind, considering both user base and functionality expansion
Technology evolution: Plan for potential technology upgrades and migration strategies
Resource allocation: Consider ongoing costs for hosting, maintenance, and development resources
Succession planning: Ensure knowledge transfer and project continuity if team members change
Compliance and legal considerations: Plan for regulatory requirements and licensing obligations that may evolve over time

2. Redefine your audience

Broaden your outreach by identifying wider audiences.

Expand beyond initial users:

Identify broader user communities
Consider different skill levels of potential users
Consider different access rights of different user groups

3. Structure the project lifecycle

Establish clear roles, timelines, and be clear and measurable in the requirements.

Formalize deliverables:

Establish clear milestones
Set deadlines for major releases
Designate a project owner
Assign responsibilities and accountability
Define in-scope and out-of-scope features
Define completion criteria for features
Update documentation with every change

4. Respect confidentiality guidelines

Adhere to institutional and legal requirements for data protection.

Ensure that you:

Follow Empa’s data protection and confidentiality policies
Classify data according to sensitivity levels
Implement appropriate access controls and authentication mechanisms
Encrypt sensitive data both in transit and at rest
Regularly review and update security measures as threats evolve

5. Automate your deployments

Embracing continuous integration and automated testing.

Quality assurance:

Implement automated deployment pipelines (CI/CD)
Set up automated testing for every code change
Use automated tools for code quality checks
Keep working in short iteration cycles

Learning and Growth

Treat each project as a learning opportunity
Share knowledge with colleagues through workshops and documentation
Stay updated on best practices and new tools

Responsible AI Usage

Always verify AI-generated code before using it in production
Understand the limitations of AI tools
Maintain human oversight over automated processes
Document when AI assistance was used and how it influenced development decisions
Be aware of potential biases in AI outputs