{"id":21673809,"url":"https://github.com/openmendel/codingstyle","last_synced_at":"2025-03-20T08:42:47.629Z","repository":{"id":104909563,"uuid":"62344090","full_name":"OpenMendel/CodingStyle","owner":"OpenMendel","description":"Coding style guidelines for OpenMendel packages","archived":false,"fork":false,"pushed_at":"2016-08-16T18:33:43.000Z","size":5,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-25T09:42:07.300Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenMendel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2016-06-30T21:43:32.000Z","updated_at":"2019-04-23T17:23:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"a6bfe81c-c582-4956-a003-a00070d0a22c","html_url":"https://github.com/OpenMendel/CodingStyle","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenMendel%2FCodingStyle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenMendel%2FCodingStyle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenMendel%2FCodingStyle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenMendel%2FCodingStyle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenMendel","download_url":"https://codeload.github.com/OpenMendel/CodingStyle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244583068,"owners_count":20476233,"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","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":"2024-11-25T13:41:24.000Z","updated_at":"2025-03-20T08:42:47.609Z","avatar_url":"https://github.com/OpenMendel.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"Style Guide\n========\n\nThis style guide is based on John Myles White's [Style.jl](https://github.com/johnmyleswhite/Style.jl) and Hadley Wickham's [R style guide](http://adv-r.had.co.nz/Style.html). These guidelines make explicit what we think are good styles. We'd ask that anyone making contributions to Mendel consider following these guidelines as well.\n\n# Naming Files and Packages\n\n* File names end in `.jl`, except for shell scripts which should not have any explicit file type extension.\n\n* GitHub repo names end in `.jl`.\n\n* Package names *do not* end in `.jl`.\n\n# Whitespace and Line Breaks\n\n* Never use tabs instead of space characters as whitespace in code.\n\n* Use two spaces when indenting:\n\n**Good style**\n\n    function myfunc(n::Integer)\n      x = 0\n      for i in 1:n\n        x += i\n      end\n      return x\n    end\n\n**Bad style**\n\n\tfunction myfunc(n::Integer)\n\t\tx = 0\n\t\tfor i in 1:n\n\t\t\tx = x + i\n\t\tend\n\t\treturn x\n\tend\n\n* When breaking a long line into multiple lines, indent the remaining lines by two spaces:\n\n**Good style**\n\n    s = a + b + c + d +\n      e + f + g + h\n\n**Bad style**\n\n    s = a + b + c + d +\n    e + f + g + h\n\n* Never place more than 80 characters on a line.\n\n* Always include a single space after a comma and never insert a space before a comma (as in regular English):\n\n**Good style**\n\n    x[1, 2]\n\n**Bad style**\n\n    x[1,2]\n    x[1 , 2]\n    x[1 ,2]\n\n\n* Always insert a single space before and after an operator, except for the `^` and `:` operators, which never have spaces around them:\n\n**Good style**\n\n    1 + 1\n    1^2\n    1:5\n\n**Bad style**\n\n    1+1\n    1 ^ 2\n    1 : 5\n\n* The spacing before-and-after rule applies to keyword arguments as well:\n\n**Good style**\n\n    myfunc(a = 1)\n\n**Bad style**\n\n    myfunc(a=1)\n\n* Use explicit parentheses with the `:` operator in complex expressions. Do not rely on Matlab-like precedence rules.\n\n**Good style**\n\n    1:(n - 1)\n\n**Bad style**\n\n    1:n - 1\n\n* Place a space before left parentheses, except in a function call:\n\n**Good style**\n\n    if (debug) do(x)\n\n**Bad style**\n\n    if(debug)do(x)\n    plot (x, y)\n\n**Better syle**\n \n    if debug do(x)\n\n* Do not place spaces around code in parentheses or square brackets (unless there’s a comma, in which case see above):\n\n**Good style**\n\n    if (debug) do(x)\n    diamonds[5, ]\n\n**Bad style**\n\n    if ( debug ) do(x)  # No spaces around debug\n    x[1,]   # Needs a space after the comma\n    x[1 ,]  # Space goes after comma not before\n\n\n# Naming Conventions\n\n* When naming variables or functions, use short lowercase names if possible:\n\n**Good style**\n\n    isna\n\n**Bad style**\n\n    isNotAvailable, is_not_available\n\n* If a variable or function name is too long to be read in all lowercase, insert underscores at word boundaries:\n\n**Good style**\n\n    lookup_table\n\n**Bad style**\n\n    lookupTable, LookupTable\n\n* When naming mutable or immutable types, use initial-cap camelcase:\n\n**Good style**\n\n    type Pair\n      val1::Float64\n      val2::Float64\n    end\n\n    immutable ImmutablePair\n      val1::Float64\n      val2::Float64\n    end\n\n**Bad style**\n\n    type pair\n      val1::Float64\n      val2::Float64\n    end\n\n    immutable immutablePair\n      val1::Float64\n      val2::Float64\n    end\n\n    immutable immutable_pair\n      val1::Float64\n      val2::Float64\n    end\n\n* When naming modules, including packages, use initial-cap camelcase, except for acronyms, for which all letters should be capitalized:\n\n**Good style**\n\n    module MyModule\n      myfunc(x::Any) = 1\n    end\n\n    using MyPackage\n    using GLM\n\n**Bad style**\n\n    module myModule\n      myfunc(x::Any) = 1\n    end\n\n    module my_module\n      myfunc(x::Any) = 1\n    end\n\n    using my_package\n    using myPackage\n    using Glm\n    using glm\n\n* When naming constants, use all caps:\n\n**Good style**\n\n    const MAGICNUMBER = 1\n\n**Bad style**\n\n    const magicnumber = 1\n    const magic_number = 1\n    const magicNumber = 1\n    const MagicNumber = 1\n\n# Mathematical Notation\n\n* Always add explicit zeros to the ends of floating point constants:\n\n**Good style**\n\n    1.0 + 2.0\n\n**Bad style**\n\n    1. + 2.\n\n* Use unicode via Latex notation for greek letters:\n\n**Good style**\n\n    α, β, γ\n\n**Bad style**\n\n    alpha, beta, gamma\n\n\n# The Type System\n\n* Always explicitly type all arguments to a function. Explicit typing makes code safer to use and clearer to an unfamiliar user:\n\n**Good style**\n\n    myfunc(x::Real, y::Real; z::Real = 1) = x + y + z\n\n**Bad style**\n\n    myfunc(x, y; z = 1) = x + y + z\n\n* When the desired types for a function are too generic to be tightly typed in Julia, use an explicit `Any`. This makes it clear that you intended for your code to work with any type of input.\n\n**Good style**\n\n    screamcase(x::Any) = uppercase(string(x))\n\n**Bad style**\n\n    screamcase(x) = uppercase(string(x))\n\n* Don't explicitly introduce a parametric type rule for a function unless it's needed to ensure correctness:\n\n**Good style**\n\n    myfunc(x::String) = print(x)\n    myfunc(x::Vector) = print(x)\n    myfunc{T \u003c: Real}(x::Vector{T}) = sum(x)\n\n**Bad style**\n\n    myfunc{T \u003c: String}(x::T) = print(x)\n    myfunc{T \u003c: Any}(x::Vector{T}) = print(x)\n\n* Try to order method definitions from least specific to most specific type constraints.\n\n**Good style**\n\n    myfunc(x::Any) = print(x)\n    myfunc(x::String) = print(uppercase(x))\n\n**Bad style**\n\n    myfunc(x::String) = print(uppercase(x))\n    myfunc(x::Any) = print(x)\n\n# Performance\n\n* Avoid creating temporary arrays, especially in loops.\n\n* Ensure that functions return a single type for each type signature of inputs.\n\n* Ensure that the type of any variable's binding does not change over the body of a function.\n\n# Code Organization\n\n* Most code should exist in a package, except for isolated scripts. Make ad hoc packages to organize your own work.\n\n* When writing packages, obey the package organization rules by placing code in `src` and tests in `test`.\n\n# Testing\n\n* Always write a separate test file for every source file you write. Specifically, place the tests for `src/myfunc.jl` in `test/myfunc.jl`.\n\n* The contents of `test/myfunc.jl` should be surrounded by a module to keep variables from leaking out:\n\n**Good style**\n\n    module TestMyFunc\n      @assert myfunc\n    end\n\n**Bad style**\n\n    @assert myfunc\n\n* Test the functionality of `src/myfunc.jl` by writing at least one test for every type/function definition in `src/myfunc.jl`. Ensure systematic code coverage.\n\n* Avoid explicit types for variables inside code unless there is potential for bugs that you need to catch.\n\n**Good style**\n\n    function myfunc()\n      x = 1\n      return x\n    end\n\n**Bad style**\n\n    function myfunc()\n      x::Int = 1\n      return x\n    end\n\n# Comments\n\n* Document functions, types, modules according to the [guide](http://docs.julialang.org/en/release-0.4/manual/documentation/).\n\n* Use `#` to begin each comment line. Leave the first and last line of a comment block empty. Comment lines are indented in the same way as code.\n\n**Good style**\n\n    function myfunc()\n      #\n      # Define a variable and return it.\n      #\n      x = 1\n      return x\n    end\n\n**Bad style**\n\n    function myfunc()\n      # define a variable and return it\n      x = 1\n      return x\n    end\n\n    function myfunc()\n    # define a variable and return it\n      x = 1\n      return x\n    end\n\n* Avoid over-commenting code. Focus on writing code that makes sense by using informative variable names and simple constructions. If you need to document a non-trivial algorithm or data structure, move that documentation into a specification file where it can be formatted nicely with diagrams and other information. English language documents are much more readable when they're not constrained by the rules for code comments.\n\n* Write separate specification documentation for non-obvious algorithms.\n\n# Error and Warning\n\n* Error messages take the format `ERROR: error message.`\n\n* Warning messages take the format `WARNING: warning message.`\n\n# Be Conservative\n\nJulia often gives you more freedom than you should use. Here are some guidelines for exhibiting self-control in the face of temptation.\n\n* Don't use `importall`. Don't even use `import`. Explicitly annotate the source of each extended function at the point of extension:\n\n**Good style**\n\n    Base.mean(x::MyNewType) = 1.0\n\n**Bad style**\n\n    import Base.median\n    median(x::MyNewType) = 1.0\n\n**Worst style**\n\n    importall Base\n    median(x::MyNewType) = 1.0\n\n#Further Suggestions for Clarity\n\n* In writing documentation, avoid computer science abbreviations such as \"foo\" and \"bar\".\n\n* Julia's C-style updating operators sometimes impede clarity.\n\n**Good style**\n\n    x = x + 1\n\n**Bad style**\n \n    x += 1\n    \n* Julia's abbreviated control structures sometimes impede clarity.\n\n**Good style**\n\n    if x == 1\n      println(\"x is 1\")\n    else\n      println(\"x is not 1\")\n    end\n    \n**Bad style**\n \n    x == 1 ? println(\"x is 1\") : println(\"x is not 1\")\n \n**Good style**\n\n    if n == 0\n      return 1\n    end\n\n**Alternative Good style**\n\n    if n == 0; return 1; end   \n\n**Bad style**\n \n    n == 0 \u0026\u0026 return 1\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenmendel%2Fcodingstyle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenmendel%2Fcodingstyle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenmendel%2Fcodingstyle/lists"}