248 lines
14 KiB
Markdown
248 lines
14 KiB
Markdown
---
|
|
description: This rule file outlines best practices for vim configuration, coding standards, and development workflows to ensure consistency, efficiency, and maintainability across vim-based projects. It includes recommendations for file organization, coding patterns, performance, security, testing, tooling, and common pitfalls.
|
|
globs: **/.vimrc, **/.vim/**, **/ftplugin/**
|
|
alwaysApply: false
|
|
---
|
|
# vim Best Practices and Coding Standards
|
|
|
|
This document outlines the best practices and coding standards for vim configuration, plugins, and general usage. Following these guidelines will ensure consistency, efficiency, and maintainability across your projects.
|
|
|
|
## 1. Code Organization and Structure
|
|
|
|
### 1.1 Directory Structure Best Practices for vim
|
|
|
|
- **~/.vim/**: This is the primary directory for vim configuration and plugins.
|
|
- **autoload/**: Contains automatically loaded scripts (e.g., plugin functions).
|
|
- **bundle/**: (Common with plugin managers like Vundle, Pathogen, or vim-plug) Stores installed plugins.
|
|
- **colors/**: Color scheme files (.vim).
|
|
- **compiler/**: Compiler settings for different languages.
|
|
- **doc/**: Documentation for plugins (help files).
|
|
- **ftdetect/**: File type detection scripts.
|
|
- **ftplugin/**: File type-specific plugin settings.
|
|
- **indent/**: Indentation scripts for different file types.
|
|
- **plugin/**: Globally loaded plugin scripts.
|
|
- **syntax/**: Syntax highlighting files for various languages.
|
|
- **templates/**: Templates for creating new files.
|
|
- **after/**: Directory to override existing configurations.
|
|
|
|
### 1.2 File Naming Conventions
|
|
|
|
- **.vimrc**: Main vim configuration file.
|
|
- **.vim**: Plugin files. Use descriptive names for your plugin scripts (e.g., `myplugin.vim`).
|
|
- `*.vim`: File type plugin files in `ftplugin` directory should be named after the filetype (e.g., `ftplugin/python.vim` for Python-specific settings).
|
|
- `*.txt`: Help files within the `doc` directory.
|
|
- `*.syn`: Syntax files within the `syntax` directory.
|
|
- `*.indent`: Indentation files within the `indent` directory.
|
|
|
|
### 1.3 Module Organization Best Practices
|
|
|
|
- **Modularize complex configurations:** Break down your `.vimrc` into smaller, manageable files. Use the `source` command to load these files in your main `.vimrc`. For example:
|
|
|
|
vim
|
|
" ~/.vimrc
|
|
source ~/.vim/config/plugins.vim
|
|
source ~/.vim/config/settings.vim
|
|
source ~/.vim/config/mappings.vim
|
|
|
|
|
|
- **Separate concerns:** Keep file type-specific settings separate from global settings. Use the `ftplugin` directory for file type-specific settings and the `plugin` directory for global plugins.
|
|
|
|
### 1.4 Component Architecture Recommendations
|
|
|
|
- **Plugins as Components:** Treat vim plugins as reusable components. Ensure that plugins perform a specific task and are well-documented.
|
|
- **Custom Functions:** Encapsulate functionality into reusable functions within your vim scripts. This promotes code reuse and maintainability.
|
|
- **Mappings and Autocommands:** Use mappings (keyboard shortcuts) and autocommands to automate tasks and customize vim's behavior.
|
|
|
|
### 1.5 Code Splitting Strategies
|
|
|
|
- **Split by Feature:** Organize your vim configuration into files based on features (e.g., plugins, settings, mappings, UI).
|
|
- **Split by File Type:** Keep language-specific settings in separate files within the `ftplugin` directory.
|
|
- **Lazy Loading:** Use plugin managers or custom autocommands to load plugins only when needed. This improves vim's startup time.
|
|
|
|
## 2. Common Patterns and Anti-patterns
|
|
|
|
### 2.1 Design Patterns Specific to vim
|
|
|
|
- **Command Pattern:** Use custom commands (`command!`) to encapsulate complex operations.
|
|
- **Observer Pattern:** Use autocommands (`autocmd`) to react to vim events (e.g., file opening, buffer changes).
|
|
- **Singleton Pattern:** For global configurations or plugin states, ensure only one instance is created.
|
|
- **Strategy Pattern:** Implement different behaviors based on file type or user settings using conditionals or function dispatch.
|
|
|
|
### 2.2 Recommended Approaches for Common Tasks
|
|
|
|
- **Plugin Management:** Use a plugin manager (Vundle, Pathogen, vim-plug) for easy installation, updates, and dependency management.
|
|
- **Syntax Highlighting:** Use a syntax highlighting plugin or create custom syntax files for specific languages or file formats.
|
|
- **Code Completion:** Use a code completion plugin (e.g., YouCompleteMe, coc.nvim) for intelligent suggestions.
|
|
- **Linting:** Integrate linters (e.g., flake8 for Python, eslint for JavaScript) to automatically check code for errors and style violations.
|
|
- **Formatting:** Integrate code formatters (e.g., clang-format, black) to automatically format code according to a defined style.
|
|
- **Navigation:** Use plugins for easy navigation within and between files (e.g., CtrlP, NERDTree).
|
|
|
|
### 2.3 Anti-Patterns and Code Smells to Avoid
|
|
|
|
- **Overly Complex `.vimrc`:** A large, monolithic `.vimrc` file is difficult to manage. Modularize your configuration.
|
|
- **Global Variables:** Avoid using global variables unnecessarily. Use function-local variables or plugin-specific variables.
|
|
- **Blocking Operations:** Avoid long-running or blocking operations in your vim scripts, as they can freeze vim's UI. Use asynchronous operations if possible.
|
|
- **Hardcoded Paths:** Avoid hardcoding file paths in your vim scripts. Use relative paths or vim variables to make your scripts more portable.
|
|
- **Ignoring Errors:** Always check for errors when executing external commands or calling vim functions.
|
|
- **Redundant Configuration:** Avoid duplicating configuration settings across multiple files. Centralize common settings in a single file.
|
|
|
|
### 2.4 State Management Best Practices
|
|
|
|
- **Plugin-Specific Variables:** Store plugin-specific state in variables prefixed with `g:`, `s:`, or `b:`, depending on the scope (global, script-local, buffer-local).
|
|
- **Options:** Use vim options (`setlocal`, `setglobal`) to store user preferences.
|
|
- **Files:** If persistence is required, store state in files (e.g., plugin settings).
|
|
|
|
### 2.5 Error Handling Patterns
|
|
|
|
- **Check Return Codes:** When calling external commands using `:!`, check the return code to ensure the command succeeded.
|
|
- **Use `:try` and `:catch`:** Use `:try` and `:catch` blocks to handle exceptions and prevent vim from crashing.
|
|
- **Display Error Messages:** Use `:echoe` to display error messages to the user.
|
|
- **Logging:** Log errors to a file for debugging purposes.
|
|
|
|
## 3. Performance Considerations
|
|
|
|
### 3.1 Optimization Techniques
|
|
|
|
- **Lazy Loading Plugins:** Load plugins only when needed using a plugin manager or autocommands. This reduces vim's startup time.
|
|
- **Avoid Excessive Mappings:** Too many mappings can slow down vim's response time. Use mappings judiciously.
|
|
- **Use Built-in Functions:** Use vim's built-in functions whenever possible, as they are generally more efficient than custom scripts.
|
|
- **Profile Your Configuration:** Use vim's profiling tools (`:profile start`, `:profile func *`, `:profile file *`, `:profile dump`) to identify performance bottlenecks in your `.vimrc`.
|
|
|
|
### 3.2 Memory Management Considerations
|
|
|
|
- **Avoid Large Strings:** Avoid creating very large strings in your vim scripts, as they can consume a lot of memory.
|
|
- **Use `delete` Command:** Use the `delete` command to free memory occupied by variables that are no longer needed.
|
|
|
|
### 3.3 Rendering Optimization (GUI vim)
|
|
|
|
- **Use a Hardware-Accelerated Terminal:** If using a GUI vim, use a terminal emulator that supports hardware acceleration for smoother rendering.
|
|
- **Optimize Color Schemes:** Use a color scheme that is optimized for performance.
|
|
|
|
### 3.4 Bundle Size Optimization (Plugins)
|
|
|
|
- **Remove Unnecessary Files:** Remove unnecessary files (e.g., documentation, examples) from your plugin bundles to reduce their size.
|
|
- **Use Git Submodules:** If your plugin depends on other plugins, use git submodules instead of copying the code directly.
|
|
|
|
### 3.5 Lazy Loading Strategies
|
|
|
|
- **Autocommands:** Load plugins when a specific file type is opened or a certain command is executed.
|
|
- **Plugin Managers:** Most plugin managers support lazy loading of plugins.
|
|
|
|
## 4. Security Best Practices
|
|
|
|
### 4.1 Common Vulnerabilities and Prevention
|
|
|
|
- **Arbitrary Code Execution:** Avoid executing arbitrary code from untrusted sources. Be careful when using plugins from unknown authors.
|
|
- **Shell Injection:** When executing shell commands using `:!`, sanitize user input to prevent shell injection attacks.
|
|
- **Information Disclosure:** Avoid storing sensitive information (e.g., passwords, API keys) in your `.vimrc` file. Use environment variables or encrypted files instead.
|
|
- **Plugin Security:** Review the source code of plugins before installing them to ensure they don't contain malicious code.
|
|
|
|
### 4.2 Input Validation
|
|
|
|
- **Sanitize User Input:** When accepting user input in your vim scripts, sanitize the input to prevent vulnerabilities.
|
|
- **Use Regular Expressions:** Use regular expressions to validate user input.
|
|
|
|
### 4.3 Authentication and Authorization
|
|
|
|
- **External Authentication:** If your vim application requires authentication, use an external authentication provider (e.g., OAuth, OpenID).
|
|
- **API Keys:** Use API keys for authorization and restrict access to sensitive resources.
|
|
|
|
### 4.4 Data Protection
|
|
|
|
- **Encryption:** Encrypt sensitive data stored in files or databases.
|
|
- **Secure Storage:** Store sensitive data in a secure storage location (e.g., a password manager).
|
|
|
|
### 4.5 Secure API Communication
|
|
|
|
- **Use HTTPS:** Always use HTTPS for communication with APIs.
|
|
- **Validate Certificates:** Validate the SSL certificates of the APIs you are communicating with.
|
|
- **Use API Keys:** Use API keys for authentication and authorization.
|
|
|
|
## 5. Testing Approaches
|
|
|
|
### 5.1 Unit Testing
|
|
|
|
- **vspec or vim-test:** These plugins facilitate writing and running unit tests for vim scripts.
|
|
- **Test Individual Functions:** Write unit tests for individual functions in your vim scripts.
|
|
- **Mock External Dependencies:** Use mocking to isolate your functions from external dependencies.
|
|
|
|
### 5.2 Integration Testing
|
|
|
|
- **Test Plugin Integrations:** Test how your plugins interact with each other and with vim's core functionality.
|
|
- **Test User Workflows:** Test common user workflows to ensure they work as expected.
|
|
|
|
### 5.3 End-to-End Testing
|
|
|
|
- **Automate vim:** Use tools like `expect` or custom scripts to automate vim and simulate user interactions.
|
|
- **Verify Functionality:** Verify that your vim application behaves as expected in a real-world environment.
|
|
|
|
### 5.4 Test Organization
|
|
|
|
- **Separate Test Files:** Store your test files in a separate directory (e.g., `test/`).
|
|
- **Follow a Consistent Naming Convention:** Use a consistent naming convention for your test files (e.g., `test/myplugin_spec.vim`).
|
|
|
|
### 5.5 Mocking and Stubbing
|
|
|
|
- **Override Functions:** Use the `:function` command to override vim functions for testing purposes.
|
|
- **Use Dummy Variables:** Create dummy variables to simulate external data.
|
|
|
|
## 6. Common Pitfalls and Gotchas
|
|
|
|
### 6.1 Frequent Mistakes
|
|
|
|
- **Inconsistent Indentation:** Using mixed tabs and spaces can lead to inconsistent indentation.
|
|
- **Ignoring File Type-Specific Settings:** Forgetting to use `setlocal` in `ftplugin` files can cause settings to apply globally.
|
|
- **Overusing Global Variables:** Using global variables unnecessarily can lead to conflicts and unexpected behavior.
|
|
|
|
### 6.2 Edge Cases
|
|
|
|
- **Unicode Characters:** Be aware of unicode characters and their potential impact on vim's behavior.
|
|
- **Line Endings:** Be mindful of line endings (LF vs. CRLF) when working with files from different operating systems.
|
|
- **File Encoding:** Ensure that your files are encoded in UTF-8 to avoid character encoding issues.
|
|
|
|
### 6.3 Version-Specific Issues
|
|
|
|
- **Check Compatibility:** Check the compatibility of plugins and scripts with your vim version.
|
|
- **Use Conditionals:** Use conditionals (`if has('feature')`) to handle version-specific differences.
|
|
|
|
### 6.4 Compatibility Concerns
|
|
|
|
- **Terminal Emulators:** Be aware of compatibility issues between vim and different terminal emulators.
|
|
- **Operating Systems:** Test your vim configuration on different operating systems to ensure compatibility.
|
|
|
|
### 6.5 Debugging Strategies
|
|
|
|
- **`:messages`:** Use the `:messages` command to view error messages and other debugging information.
|
|
- **`:echo`:** Use the `:echo` command to print values of variables and expressions.
|
|
- **`:debug`:** Use the `:debug` command to step through your vim scripts line by line.
|
|
- **Logging:** Log errors and debugging information to a file.
|
|
|
|
## 7. Tooling and Environment
|
|
|
|
### 7.1 Recommended Development Tools
|
|
|
|
- **Plugin Manager:** Vundle, Pathogen, vim-plug.
|
|
- **Syntax Checker:** Syntastic, ALE.
|
|
- **Code Completion:** YouCompleteMe, coc.nvim.
|
|
- **Fuzzy Finder:** CtrlP, fzf.vim.
|
|
- **Color Scheme Designer:** [https://github.com/lifepillar/vim-solarized](mdc:https:/github.com/lifepillar/vim-solarized).
|
|
|
|
### 7.2 Build Configuration Best Practices
|
|
|
|
- **Automated Builds:** Use a build system (e.g., Make, Ant, Gradle) to automate the process of building and testing your vim application.
|
|
- **Version Control:** Use version control (e.g., Git) to track changes to your code and configuration.
|
|
|
|
### 7.3 Linting and Formatting
|
|
|
|
- **Use a Linter:** Integrate a linter into your vim workflow to automatically check code for errors and style violations.
|
|
- **Use a Formatter:** Integrate a code formatter to automatically format code according to a defined style.
|
|
- **Follow a Style Guide:** Follow a consistent style guide (e.g., PEP 8 for Python, Google Style Guide for C++) to ensure code readability.
|
|
|
|
### 7.4 Deployment Best Practices
|
|
|
|
- **Use a Package Manager:** Use a package manager (e.g., APT, Yum, Homebrew) to install vim and its dependencies.
|
|
- **Automate Deployment:** Use a deployment tool (e.g., Ansible, Chef, Puppet) to automate the deployment process.
|
|
|
|
### 7.5 CI/CD Integration
|
|
|
|
- **Integrate with CI/CD:** Integrate your vim project with a CI/CD system (e.g., Jenkins, Travis CI, CircleCI) to automatically build, test, and deploy your code. |