oh-my-customcode 0.1.0

package/templates/guides/kotlin/coding-conventions.md

@@ -0,0 +1,247 @@
+# Kotlin Coding Conventions
+
+> Source: https://kotlinlang.org/docs/coding-conventions.html
+
+## Source Code Organization
+
+### Directory Structure
+
+Follow package structure with common root omitted:
+- `org.example.kotlin.network.socket` → `network/socket` subdirectory
+
+### Source File Names
+
+| Content | File Name |
+|---------|-----------|
+| Single class | `MyClass.kt` |
+| Multiple declarations | `ProcessDeclarations.kt` |
+| Platform-specific | `Platform.jvm.kt` |
+
+### Class Layout
+
+1. Property declarations and initializer blocks
+2. Secondary constructors
+3. Method declarations
+4. Companion object
+
+```kotlin
+class MyClass(val name: String) {
+    // 1. Properties
+    private val items = mutableListOf<Item>()
+
+    init {
+        // initializer block
+    }
+
+    // 2. Secondary constructors
+    constructor() : this("default")
+
+    // 3. Methods
+    fun doSomething() { }
+
+    // 4. Companion object
+    companion object {
+        const val TAG = "MyClass"
+    }
+}
+```
+
+## Naming Conventions
+
+| Element | Style | Example |
+|---------|-------|---------|
+| Packages | lowercase | `org.example.project` |
+| Classes | UpperCamelCase | `DeclarationProcessor` |
+| Functions | lowerCamelCase | `processDeclarations()` |
+| Properties | lowerCamelCase | `declarationCount` |
+| Constants | UPPER_SNAKE_CASE | `MAX_COUNT` |
+| Backing properties | underscore prefix | `_elementList` |
+
+### Acronyms
+
+- 2 letters: both uppercase (`IOStream`)
+- 3+ letters: capitalize first only (`XmlFormatter`)
+
+## Formatting
+
+### Indentation
+
+```kotlin
+if (elements != null) {
+    for (element in elements) {
+        // 4 spaces indentation
+    }
+}
+```
+
+### Horizontal Whitespace
+
+```kotlin
+// Binary operators with spaces
+val sum = a + b
+
+// No space around range
+for (i in 0..n) { }
+
+// No space around dot
+foo.bar().filter { it > 2 }
+
+// Space after control keywords
+if (condition) { }
+```
+
+### Colons
+
+```kotlin
+// Type and supertype: space before
+abstract class Foo<out T : Any> : IFoo {
+    // Declaration and type: no space before
+    abstract fun foo(a: Int): T
+}
+```
+
+### Function Signatures
+
+```kotlin
+// Short: single line
+fun foo(a: Int): String = a.toString()
+
+// Long: break parameters
+fun longMethodName(
+    argument: ArgumentType = defaultValue,
+    argument2: AnotherArgumentType,
+): ReturnType {
+    // body
+}
+```
+
+### Trailing Commas
+
+```kotlin
+class Person(
+    val firstName: String,
+    val lastName: String,
+    val age: Int, // trailing comma
+)
+```
+
+## Idiomatic Patterns
+
+### Immutability
+
+```kotlin
+// Prefer val
+val name = "Kotlin"
+
+// Prefer immutable collections
+val items = listOf(1, 2, 3)
+```
+
+### Default Parameters
+
+```kotlin
+// Prefer over overloads
+fun read(
+    b: ByteArray,
+    off: Int = 0,
+    len: Int = b.size,
+) { }
+```
+
+### Expression Bodies
+
+```kotlin
+// Prefer for simple functions
+fun square(x: Int) = x * x
+```
+
+### Conditionals
+
+```kotlin
+// Use if for binary
+return if (x) foo() else bar()
+
+// Use when for multiple
+return when (x) {
+    0 -> "zero"
+    1 -> "one"
+    else -> "many"
+}
+```
+
+### Functional Operations
+
+```kotlin
+// Prefer
+list.filter { it > 10 }
+    .map { it * 2 }
+    .take(5)
+
+// Over manual loops
+```
+
+### Ranges
+
+```kotlin
+// Good: open-ended range
+for (i in 0..<n) { }
+
+// Avoid
+for (i in 0..n - 1) { }
+```
+
+## Null Safety
+
+```kotlin
+// Safe call
+val length = text?.length
+
+// Elvis operator
+val name = user?.name ?: "Unknown"
+
+// Let for non-null
+user?.let {
+    println("Hello, ${it.name}")
+}
+
+// Not-null assertion (use sparingly)
+val name = user!!.name
+```
+
+## Documentation
+
+```kotlin
+/**
+ * Returns the absolute value of the given [number].
+ */
+fun abs(number: Int): Int = if (number < 0) -number else number
+
+/**
+ * A group of *members*.
+ *
+ * This class has no useful logic; it's just a documentation example.
+ *
+ * @property name the name of this group.
+ * @constructor Creates an empty group.
+ */
+class Group(val name: String) {
+    /**
+     * Adds a [member] to this group.
+     * @return the new size of the group.
+     */
+    fun add(member: Member): Int { ... }
+}
+```
+
+## Avoid Redundant Constructs
+
+```kotlin
+// Avoid explicit Unit return
+fun foo() { } // not: fun foo(): Unit { }
+
+// Avoid semicolons
+val x = 1 // not: val x = 1;
+
+// Use simple string templates
+"$name" // not: "${name}"
+```

package/templates/guides/kotlin/idioms.md

@@ -0,0 +1,234 @@
+# Kotlin Idioms
+
+> Source: https://kotlinlang.org/docs/idioms.html
+
+## Data Classes
+
+```kotlin
+data class Customer(val name: String, val email: String)
+```
+
+Provides:
+- `equals()` / `hashCode()`
+- `toString()`: `"Customer(name=John, email=john@example.com)"`
+- `copy()` function
+- `componentN()` functions
+
+## Default Parameter Values
+
+```kotlin
+fun foo(a: Int = 0, b: String = "") { }
+```
+
+## Filtering Collections
+
+```kotlin
+val positives = list.filter { it > 0 }
+
+// or with explicit type
+val positives = list.filter { x -> x > 0 }
+```
+
+## Checking Element Presence
+
+```kotlin
+if ("john@example.com" in emailsList) { }
+if ("jane@example.com" !in emailsList) { }
+```
+
+## String Interpolation
+
+```kotlin
+println("Name: $name")
+println("Age: ${person.age}")
+```
+
+## Instance Checks
+
+```kotlin
+when (x) {
+    is Foo -> ...
+    is Bar -> ...
+    else -> ...
+}
+```
+
+## Read-only Collections
+
+```kotlin
+val list = listOf("a", "b", "c")
+val map = mapOf("a" to 1, "b" to 2, "c" to 3)
+```
+
+## Accessing Maps
+
+```kotlin
+val map = mapOf("a" to 1)
+println(map["a"]) // prints 1
+```
+
+## Traversing Maps
+
+```kotlin
+for ((k, v) in map) {
+    println("$k -> $v")
+}
+```
+
+## Ranges
+
+```kotlin
+for (i in 1..100) { }      // closed range: 1 to 100
+for (i in 1..<100) { }     // half-open: 1 to 99
+for (i in 2..10 step 2) { }
+for (i in 10 downTo 1) { }
+```
+
+## Lazy Property
+
+```kotlin
+val p: String by lazy {
+    // compute the string
+}
+```
+
+## Extension Functions
+
+```kotlin
+fun String.spaceToCamelCase() { }
+"Convert this to camelcase".spaceToCamelCase()
+```
+
+## Singleton
+
+```kotlin
+object Resource {
+    val name = "Name"
+}
+```
+
+## Instantiate Abstract Class
+
+```kotlin
+abstract class MyAbstractClass {
+    abstract fun doSomething()
+}
+
+val myObject = object : MyAbstractClass() {
+    override fun doSomething() { }
+}
+```
+
+## if-not-null Shorthand
+
+```kotlin
+// Simple
+val length = files?.size
+
+// With else
+val length = files?.size ?: 0
+
+// With let
+files?.let {
+    println(it.size)
+}
+```
+
+## Return on when
+
+```kotlin
+fun transform(color: String): Int {
+    return when (color) {
+        "Red" -> 0
+        "Green" -> 1
+        "Blue" -> 2
+        else -> throw IllegalArgumentException("Invalid color")
+    }
+}
+```
+
+## try-catch Expression
+
+```kotlin
+val result = try {
+    count()
+} catch (e: ArithmeticException) {
+    throw IllegalStateException(e)
+}
+```
+
+## if Expression
+
+```kotlin
+val y = if (x == 1) {
+    "one"
+} else if (x == 2) {
+    "two"
+} else {
+    "other"
+}
+```
+
+## Builder-style Usage
+
+```kotlin
+fun arrayOfMinusOnes(size: Int): IntArray {
+    return IntArray(size).apply { fill(-1) }
+}
+```
+
+## Single-expression Functions
+
+```kotlin
+fun theAnswer() = 42
+
+// equivalent to
+fun theAnswer(): Int {
+    return 42
+}
+```
+
+## Call Multiple Methods (with)
+
+```kotlin
+class Turtle {
+    fun penDown()
+    fun penUp()
+    fun turn(degrees: Double)
+    fun forward(pixels: Double)
+}
+
+val myTurtle = Turtle()
+with(myTurtle) {
+    penDown()
+    for (i in 1..4) {
+        forward(100.0)
+        turn(90.0)
+    }
+    penUp()
+}
+```
+
+## Configure Object (apply)
+
+```kotlin
+val myRectangle = Rectangle().apply {
+    length = 4
+    breadth = 5
+    color = 0xFAFAFA
+}
+```
+
+## Swap Variables
+
+```kotlin
+var a = 1
+var b = 2
+a = b.also { b = a }
+```
+
+## TODO: Marking Incomplete
+
+```kotlin
+fun calcTaxes(): BigDecimal = TODO("Waiting for feedback from accounting")
+```

package/templates/guides/kotlin/index.yaml

@@ -0,0 +1,26 @@
+# Kotlin Guide
+
+metadata:
+  name: kotlin
+  description: Kotlin language reference documentation
+
+source:
+  type: external
+  origin: kotlinlang.org
+  urls:
+    - https://kotlinlang.org/docs/coding-conventions.html
+    - https://kotlinlang.org/docs/idioms.html
+    - https://developer.android.com/kotlin/style-guide
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: coding-conventions
+    path: ./coding-conventions.md
+    description: Official Kotlin coding conventions
+
+  - name: idioms
+    path: ./idioms.md
+    description: Idiomatic Kotlin patterns
+
+used_by:
+  - kotlin-expert

package/templates/guides/python/index.yaml

@@ -0,0 +1,26 @@
+# Python Guide
+
+metadata:
+  name: python
+  description: Python language reference documentation
+
+source:
+  type: external
+  origin: python.org
+  urls:
+    - https://peps.python.org/pep-0008/
+    - https://peps.python.org/pep-0020/
+    - https://google.github.io/styleguide/pyguide.html
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: pep8-style-guide
+    path: ./pep8-style-guide.md
+    description: PEP 8 - Official Python Style Guide
+
+  - name: zen-of-python
+    path: ./zen-of-python.md
+    description: PEP 20 - The Zen of Python
+
+used_by:
+  - python-expert

package/templates/guides/python/pep8-style-guide.md

@@ -0,0 +1,202 @@
+# PEP 8 - Style Guide for Python Code
+
+> Source: https://peps.python.org/pep-0008/
+
+## Introduction
+
+This document gives coding conventions for the Python code comprising the standard library. The key insight is that code is read much more often than it is written. Prioritize readability.
+
+## Code Layout
+
+### Indentation
+
+Use 4 spaces per indentation level.
+
+```python
+# Aligned with opening delimiter
+foo = long_function_name(var_one, var_two,
+                         var_three, var_four)
+
+# Hanging indent with additional level
+def long_function_name(
+        var_one, var_two, var_three,
+        var_four):
+    print(var_one)
+```
+
+### Maximum Line Length
+
+- Limit all lines to 79 characters
+- Docstrings/comments: limit to 72 characters
+- Teams may agree on longer lines (up to 99)
+
+### Binary Operators
+
+Break before binary operators:
+
+```python
+# Correct:
+income = (gross_wages
+          + taxable_interest
+          + (dividends - qualified_dividends))
+```
+
+### Blank Lines
+
+- Two blank lines around top-level definitions
+- One blank line between method definitions
+- Extra blank lines sparingly to separate logical sections
+
+## Imports
+
+```python
+# Standard library
+import os
+import sys
+
+# Third party
+import numpy as np
+
+# Local
+from myproject import mymodule
+```
+
+Rules:
+- One import per line
+- Absolute imports preferred
+- Avoid wildcard imports
+
+## Whitespace
+
+```python
+# Correct:
+spam(ham[1], {eggs: 2})
+x = 1
+y = 2
+long_variable = 3
+
+# Wrong:
+spam( ham[ 1 ], { eggs: 2 } )
+x             = 1
+y             = 2
+long_variable = 3
+```
+
+## Comments
+
+### Block Comments
+
+```python
+# This is a block comment that
+# spans multiple lines and describes
+# the following code block.
+```
+
+### Inline Comments
+
+```python
+x = x + 1  # Increment x
+```
+
+### Docstrings
+
+```python
+def complex(real=0.0, imag=0.0):
+    """Form a complex number.
+
+    Keyword arguments:
+    real -- the real part (default 0.0)
+    imag -- the imaginary part (default 0.0)
+    """
+    pass
+```
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Module | lowercase_underscore | `my_module` |
+| Package | lowercase | `mypackage` |
+| Class | CapWords | `MyClass` |
+| Exception | CapWords + Error | `CustomError` |
+| Function | lowercase_underscore | `my_function` |
+| Variable | lowercase_underscore | `my_var` |
+| Constant | UPPER_UNDERSCORE | `MAX_SIZE` |
+| Method | lowercase_underscore | `my_method` |
+
+### Special Naming
+
+- `_single_leading`: weak "internal use" indicator
+- `__double_leading`: name mangling in classes
+- `__double_both__`: "magic" methods
+
+## Programming Recommendations
+
+### Comparisons
+
+```python
+# Correct:
+if foo is not None:
+if isinstance(obj, int):
+
+# Wrong:
+if foo != None:
+if type(obj) is int:
+```
+
+### Sequences
+
+```python
+# Correct:
+if not seq:
+if seq:
+
+# Wrong:
+if len(seq) == 0:
+if len(seq) > 0:
+```
+
+### Exception Handling
+
+```python
+# Correct:
+try:
+    value = collection[key]
+except KeyError:
+    return key_not_found(key)
+
+# Wrong:
+try:
+    value = collection[key]
+except:  # Bare except
+    return key_not_found(key)
+```
+
+### Context Managers
+
+```python
+# Correct:
+with open('file.txt') as f:
+    contents = f.read()
+
+# Wrong:
+f = open('file.txt')
+contents = f.read()
+f.close()
+```
+
+### Return Statements
+
+```python
+# Correct:
+def foo(x):
+    if x >= 0:
+        return math.sqrt(x)
+    else:
+        return None
+
+# Wrong:
+def foo(x):
+    if x >= 0:
+        return math.sqrt(x)
+```