{"id":30617498,"url":"https://github.com/qaware/qaway-linter","last_synced_at":"2025-08-30T10:48:22.343Z","repository":{"id":268842849,"uuid":"905615222","full_name":"qaware/qaway-linter","owner":"qaware","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-17T14:05:17.000Z","size":30,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-18T02:04:12.727Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qaware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-19T07:26:20.000Z","updated_at":"2025-04-17T14:03:25.000Z","dependencies_parsed_at":"2025-04-20T06:46:04.377Z","dependency_job_id":null,"html_url":"https://github.com/qaware/qaway-linter","commit_stats":null,"previous_names":["qaware/qaway-linter"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/qaware/qaway-linter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fqaway-linter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fqaway-linter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fqaway-linter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fqaway-linter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qaware","download_url":"https://codeload.github.com/qaware/qaway-linter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fqaway-linter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272839679,"owners_count":25001862,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-30T10:48:20.692Z","updated_at":"2025-08-30T10:48:22.218Z","avatar_url":"https://github.com/qaware.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QAway Linter\n\nThe QAway linter for [golangci-lint](https://golangci-lint.run/) enforces coding best practices, especially in terms of\ndocumentation. It allows you to define rules for your codebase with maximum flexibility as different parts of your code\nmay require different rules.\n\nThe linter is not yet integrated directly into [go-langci-lint](https://golangci-lint.run/), but can be used as\na [custom plugin](https://golangci-lint.run/plugins/module-plugins/) (see [Usage](#usage)).\n\n## Rules\n\nThis chapter demonstrates the rules that can be configured in the `qaway-linter` plugin. The rules are defined in the\nconfiguration and can be enabled or disabled for specific packages (see [Usage](#usage)).\n\n### Functions: minCommentDensity\n\nA method must have at least `minCommentDensity` of comments (headline + inline) compared to its lines of code. Often\nused in combination with the filter `minLinesOfCode` to exclude small methods from this rule.\n\nExample function for `minCommentDensity: 0.1`:\n\n```go\nfunc WithoutComments() string {\nstring := \"Hello, World!\"\nreturn string\n}\n```\n\nViolation: `Method 'WithoutComments' has less than 10% comment density. Actual: 0%`\n\n### Functions: requireHeadlineComment\n\nA headline comment is required for every method. A headline comment is the comment on top of the method.\n\nExample function without headline comment:\n\n```go\nfunc WithoutHeadlineComment() string {\n// This is an inline comment\nstring := \"Hello, World!\"\nreturn string\n}\n```\n\nViolation: `Method 'WithoutHeadlineComment' is missing required headline comment`\n\n### Functions: trivialCommentThreshold\n\nTrivial headline comments (similarity to method name) are not allowed.\nThe threshold indicates the similarity to the method name.\nA higher threshold indicates a higher required similarity for throwing a violation, resulting in less warnings. A good\nstarting point is a value of `0.3`.\n\nExample function with trivial comment:\n\n```go\n// DownloadArtifacts downloads the artifacts\nfunc DownloadArtifacts() string {\nstring := \"Hello, World!\"\nreturn string\n}\n```\n\nViolation: `Method 'downloadArtifacts' has a trivial comment. Similarity to method name: 40%`\n\n### Functions: minLoggingDensity\n\nAmount of logging statements compared to lines of code. The rule helps enforcing a minimum amount of logging in certain\naspects of your codebase.\n\nExample function with low logging density:\n\n```go\nfunc WithoutLogging() string {\nstring := \"Hello, World!\"\nreturn string\n}\n```\n\nViolation: `Method 'WithoutLogging' has less than 0% logging density. Actual: 0%`\n\n### Interfaces: requireHeadlineComment\n\nA headline comment is required for every interface.\n\nExample interface without headline comment:\n\n```go\ntype WithoutHeadlineComment interface {\nMethodWithoutComment()\n}\n```\n\nViolation: `Interface 'WithoutHeadlineComment' is missing required headline comment`\n\n### Interfaces: requireMethodComment\n\nA comment is required for every method in an interface.\n\nExample interface method without comment:\n\n```go\ntype WithoutMethodComment interface {\nMethodWithoutComment()\n}\n```\n\nViolation: `Method 'MethodWithoutComment' is missing required comment`\n\n### Structs: requireHeadlineComment\n\nA headline comment is required for every struct.\n\nExample struct without headline comment:\n\n```go\ntype WithoutHeadlineComment struct {\nFieldWithoutComment string\n}\n```\n\nViolation: `Struct 'WithoutHeadlineComment' is missing required headline comment`\n\n### Structs: requireFieldComment\n\nA comment is required for every field in a struct.\n\nExample struct field without comment:\n\n```go\ntype WithoutFieldComment struct {\nFieldWithoutComment string\n}\n```\n\nViolation: `Field 'FieldWithoutComment' is missing required comment`\n\n## Usage\n\n1. Create a file called `.custom-gcl.yml` in your projects root directory with the following content:\n\n```yaml\nversion: v1.62.2 # TODO: update to latest version (see https://github.com/golangci/golangci-lint/releases/tag/v1.62.2)\nplugins:\n  - module: 'github.com/qaware/qaway-linter'\n    import: 'github.com/qaware/qaway-linter'\n    version: v0.0.1 # TODO: use latest version from GitHub\n```\n\n2. Execute `golangci-lint custom` in the same directory to build a custom version of golangci-lint with the\n   `qaway-linter` plugin.\n\n3. Extend the configuration in your `.golangci.yml`. Customize the rules according to your codebase. Note that more\n   concrete packages override the configuration of more general packages .\n\n```yaml\nlinters:\n  enable:\n    # add to existing list if linters.disable-all is set to true\n    - qawaylinter\n\nlinter-settings:\n  custom:\n    qawaylinter:\n      type: \"module\"\n      description: \"Checks for appropriate documentation in code\"\n      settings:\n        rules:\n          - packages: [ \"github.com/myorg/myrepo\" ]\n            # This rule demonstrates all available configuration options\n            # If a parameter is not set, it is not enforced.\n            functions:\n              filters:\n                # Apply parameters only to functions with at least 10 lines of code\n                minLinesOfCode: 10\n              params:\n                # A method must have at least 10% of comments (headline + inline) compared to its lines of code\n                minCommentDensity: 0.1\n                # A headline comment is required for every method\n                requireHeadlineComment: true\n                # Trivial comments (similarity to method name) are not allowed. \n                # The threshold indicates the similarity to the method name.\n                # A higher threshold indicates a higher similarity, resulting in less warnings.\n                trivialCommentThreshold: 0.3\n                # Amount of logging statements compared to lines of code. \n                minLoggingDensity: 0.0\n            interfaces:\n              params:\n                # A headline comment is required for every interface\n                requireHeadlineComment: true\n                # A comment is required for every method in an interface\n                requireMethodComment: true\n            structs:\n              params:\n                # A headline comment is required for every struct\n                requireHeadlineComment: true\n                # A comment is required for every field in a struct\n                requireFieldComment: false\n          - packages: [ \"github.com/myorg/myrepo/subpkg\" ] # rules for subpackage override super packages\n            functions:\n              filters:\n                minLinesOfCode: 20\n              params:\n                trivialCommentThreshold: 0.5\n                minLoggingDensity: 0.1\n```\n\n4. Execute the custom version by running `./custom-gcl run` in your project's root directory.\n\n## Exclusions\n\nAdd `// nolint:qawaylinter` to the line you want to exclude from the linter. It is not possible to disable individual\nrules from the configuration.\n\n## Internal architecture\n\nA generic `Rule` interface is defined in [rule.go](rule.go). Each rule implements this interface and is responsible for\nchecking a specific aspect of the code. The `Rule` interface defines three methods:\n\n* `isApplicable`: Checks if the rule is applicable to the given code element (node).\n* `Analyse`: Analyzes the code element and returns a list of findings.\n* `Apply`: Validates if the results from the analysis violate rules from the configuration and reports errors.\n\nEach rule is called in the [analyser](analyser.go) for each code element. The analyser is responsible for traversing the\ncode and calling the rules. New rules must be added to the analyser to be executed.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqaware%2Fqaway-linter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqaware%2Fqaway-linter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqaware%2Fqaway-linter/lists"}