79:T41e,Method names are not merely labels—they are **the primary mechanism for conveying design intent**. When developers encounter your API, names are what they see first in autocomplete, what they search for, what they discuss in code reviews, and what they remember. The cognitive load imposed by poor naming accumulates across every interaction with your API. **The Cost of Poor Naming** Poor method names create a cascade of problems: 1. **Increased learning curve** — Developers must read documentation for every method instead of inferring purpose from names. 2. **Higher defect rates** — When names don't reflect behavior, developers make incorrect assumptions, leading to bugs. 3. **Reduced discoverability** — In autocomplete scenarios, vague names don't surface when developers search for functionality. 4. **Code review friction** — Reviewers must constantly verify that method names match their implementations. 5. **Maintenance burden** — Future maintainers inherit confusion, often perpetuating or worsening naming inconsistencies.7a:T434,**Accessor Methods (Getters)** Accessors retrieve internal state without modification. They should: - Start with `get` (or language-appropriate equivalent) - Return a value (never void) - Be side-effect free - Be idempotent (same result on repeated calls, assuming no external mutation) ```java // Good accessors String getName() int getAge() List getOrders() Optional

getShippingAddress() // Boolean accessors use is/has/can boolean isActive() boolean hasOrders() boolean canEdit() ``` **Mutator Methods (Setters)** Mutators modify internal state. They should: - Start with `set` for simple property assignment - Use more specific verbs for complex mutations - Consider returning `this` for fluent APIs - Consider returning the previous value if useful ```java // Simple setters void setName(String name) void setAge(int age) // Fluent setters (return this) User setName(String name) Builder setAge(int age) // Complex mutations deserve specific names void addPermission(Permission perm) void removeFromCart(Item item) void incrementRetryCount() ```7b:T4c4,**Factory Method Naming** Factory methods create new instances. Common patterns include: **Prefix Patterns**: - `create` — General-purpose creation, may involve setup - `of` — Static factory, lightweight conversion - `from` — Build from a different representation - `new` — Explicit constructor-like creation (some languages) - `build` — Result of builder pattern ```java // create — General factory Connection createConnection(Config config) User createGuestUser() // of — Static factory for simple creation Optional of(T value) List of(T... elements) Money of(BigDecimal amount, Currency currency) // from — Conversion from different representation Instant fromEpochMilli(long millis) UserId fromString(String id) Order fromJson(String json) // build — Builder pattern result HttpRequest build() Configuration build() ``` **The `getInstance()` Debate** For singleton access, `getInstance()` is traditional but reveals implementation. Consider `get()` on a well-named accessor object: ```java // Traditional Logger logger = Logger.getInstance(); // Alternative—context provides clarity Logger logger = Loggers.getDefault(); Logger logger = LoggerFactory.getLogger(MyClass.class); ```7c:T473,**Query Method Naming** Query methods answer questions about state without modifying it. They are the cornerstone of the Command-Query Separation (CQS) principle. **Boolean Queries**: Boolean methods should read like questions: ```java // Existence checks boolean exists() boolean isEmpty() boolean isPresent() // State queries boolean isActive() boolean isValid() boolean isExpired() // Capability queries boolean canEdit() boolean canDelete() boolean supports(Feature feature) // Containment queries boolean contains(Element element) boolean hasKey(String key) boolean hasPermission(Permission perm) ``` **Collection/Count Queries**: ```java // Size queries int size() int count() int length() // Collection retrieval List findAll() List findByCategory(Category cat) Set getActiveUsers() // Aggregate queries Money getTotalRevenue() double getAverageRating() int countByStatus(Status status) ``` **Avoid Query Method Side Effects**: Query methods must not have side effects. A method like `getNextId()` that increments a counter violates this principle; prefer `allocateNextId()` to signal the side effect.7d:T4bf,# API Naming System: Order Management ## Verb Vocabulary | Verb | Meaning | Returns | Throws | |------|---------|---------|--------| | get | Retrieve by identifier | Entity (non-null) | NotFoundException | | find | Search/filter | Entity? or List | Never | | create | Construct new entity | Created entity | ValidationException | | update | Modify existing entity | Updated entity | NotFoundException | | delete | Remove entity | void | Never (idempotent) | | submit | Transition to submitted state | void | InvalidStateException | | cancel | Transition to cancelled state | void | InvalidStateException | | archive | Move to archived state | void | InvalidStateException | ## Grammatical Patterns - Retrieval: `{get|find}{Entity}[By{Criteria}]` - Examples: `getOrder()`, `findOrdersByCustomer()`, `findByStatus()` - Creation: `create{Entity}` - Examples: `createOrder()`, `createLineItem()` - State transitions: `{verb}{Entity}` or just `{verb}()` if context is clear - Examples: `submitOrder()`, `order.submit()`, `order.cancel()` ## Domain Terminology - Use: Order, LineItem, Customer, Product, Shipment - Avoid: Transaction, Entry, User (where Customer is meant), Item (where Product is meant)71:{"json":{"id":"seed_c4726a5376a857c8b11343357fd4d188","slug":"method-signature-design","category":"System Design (LLD)","topic":"Method Signature Design","title":"Method Signature Design","description":"Master the art and science of designing method signatures that are intuitive, consistent, and maintainable. Learn naming conventions, parameter design, return type strategies, and overloading guidelines from a Principal Engineer perspective.","difficulty":"INTERMEDIATE","estimatedMinutes":60,"pages":[{"id":"seed_98b07a3e307cc17881df8a9911dabb61","title":"Method Naming Conventions","order":0,"content":[{"id":"opening-hook","title":"The Name Is the Interface","content":[{"data":{"content":"Before a single line of documentation is read, before parameter types are examined, before return values are considered—a method name is encountered. That name is not merely an identifier; it is a **promise**. It declares intent. It sets expectations. It either guides understanding or sows confusion.\n\nIn the world of API design, method naming is not a trivial detail relegated to style guides and linting rules. It is the **first act of communication** between the API designer and every developer who will ever use that API. A well-named method reveals its purpose instantly. A poorly-named method creates friction that compounds across every invocation, every code review, every debugging session.\n\nConsider the difference between `process()` and `validateAndSubmitOrder()`. The former tells you almost nothing; the latter tells you almost everything. That distinction—multiplied across hundreds of methods in a codebase—is the difference between APIs that developers love and APIs that developers dread."},"type":"text"},{"data":{"icon":"Target","title":"What You Will Master","content":"By the end of this page, you will understand the foundational principles of method naming, recognize common anti-patterns, and apply proven naming strategies that make APIs self-documenting and intuitive. You'll think about naming the way Principal Engineers do—as a design decision with lasting consequences.","variant":"info"},"type":"callout"}]},{"id":"why-names-matter","title":"Why Method Names Matter","content":[{"data":{"content":"$79"},"type":"text"},{"data":{"rows":[["Discovery/Learning","Self-documenting, intuitive exploration","Requires documentation for every method"],["Implementation","Code reads like natural language","Constant back-and-forth with docs"],["Code Review","Intent is immediately apparent","Reviewers question every method call"],["Debugging","Call stacks reveal behavior flow","Method names obscure execution path"],["Maintenance","Changes are confidently localized","Fear of unintended side effects"],["Onboarding","New developers ramp up quickly","Tribal knowledge required to understand"]],"caption":"Impact of Naming Quality Across the Development Lifecycle","headers":["Development Phase","Good Naming Impact","Poor Naming Impact"]},"type":"table"},{"data":{"icon":"AlertCircle","title":"The Naming Debt Compound Effect","content":"Poor naming is a form of technical debt that compounds silently. Unlike performance issues that manifest as measurable slowdowns, naming debt manifests as slower development, more bugs, and developer frustration—all of which are harder to quantify but no less real.","variant":"warning"},"type":"callout"}],"titleType":"number","titleNumber":1},{"id":"foundational-principles","title":"Foundational Naming Principles","content":[{"data":{"content":"Effective method naming rests on several foundational principles that transcend specific programming languages or frameworks. These principles should guide every naming decision you make."},"type":"text"},{"data":{"items":["**Reveal Intent, Not Implementation** — A method name should describe *what* the method does, not *how* it does it. `sendEmail()` is better than `useSmtpToTransmit()`. Implementation may change; intent should remain stable.","**Be Precise, Not Vague** — Avoid generic names like `handle()`, `process()`, `manage()`, or `execute()`. These words carry almost no semantic meaning. Prefer `processPayment()`, `handleAuthenticationFailure()`, or `executeScheduledJob()`.","**Use Domain Vocabulary** — Names should come from the problem domain, not technical jargon. If the business calls it an 'Order', don't call it a 'Transaction'. Ubiquitous language from Domain-Driven Design applies here.","**Maintain Consistent Conventions** — If you use `get` for retrieval in one place, don't use `fetch`, `retrieve`, or `obtain` elsewhere. Consistency reduces cognitive load dramatically.","**Optimize for Readability, Not Brevity** — A longer, clearer name is almost always better than a shorter, ambiguous one. `calculateMonthlyInterestPayment()` beats `calcMIP()`.","**Consider the Call Site** — Methods are read at call sites far more often than at definition sites. `order.cancel()` reads better than `order.setCancelled(true)`."],"title":{"icon":"Target","text":"Core Naming Principles","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"content":"**The Grain of Truth in Brevity**\n\nWhile we advocate for clarity over brevity, there's a legitimate concern about overly long names. The key is to achieve **maximum clarity per character**. Each word in a method name should add meaning. Remove words that don't contribute.\n\nFor example, `getUserFromDatabaseById()` can be simplified to `getUser()` if the 'from database' part is implied by the class context and 'by ID' is implied by the parameter type. Context already communicates some information; don't repeat it in the name."},"type":"text"},{"data":{"icon":"Lightbulb","title":"The Newspaper Test","content":"Read your method call in the context of surrounding code. Does it read like a sentence in a newspaper article? Good names allow code to be read almost like prose: `if (user.canAccessResource(document)) { audit.logAccessGranted(user, document); }`","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":2},{"id":"verb-first-patterns","title":"Verb-First Naming Patterns","content":[{"data":{"content":"In most programming languages, methods represent **actions**—things an object can do. Actions are naturally described with verbs. Therefore, the predominant convention is to start method names with a verb that describes the action being performed.\n\n**Standard Verb Prefixes and Their Meanings**\n\nOver decades of software development, certain verb prefixes have acquired standardized meanings. Deviating from these meanings creates confusion; adhering to them leverages developers' existing mental models."},"type":"text"},{"data":{"rows":[["`get`","Retrieve a value","No side effects, returns non-null or throws","`getUser(id)`"],["`find`","Search for a value","No side effects, may return null","`findUserByEmail(email)`"],["`set`","Assign a value","Mutates state, usually returns void","`setPassword(newPassword)`"],["`is/has/can`","Query boolean state","No side effects, returns boolean","`isActive()`, `hasPermission()`"],["`create`","Construct a new entity","Returns new object, may persist","`createOrder(items)`"],["`delete/remove`","Eliminate an entity","Mutates state, idempotent preferred","`deleteUser(id)`"],["`update`","Modify existing entity","Mutates state, typically partial","`updateProfile(changes)`"],["`compute/calculate`","Derive a value from inputs","Pure function, deterministic","`calculateTax(order)`"],["`validate`","Check correctness","No mutation, returns boolean or throws","`validateEmail(email)`"],["`parse`","Transform string to type","Pure function, may throw on bad input","`parseDate(dateString)`"],["`format`","Transform type to string","Pure function, deterministic","`formatCurrency(amount)`"],["`ensure/require`","Guarantee a condition","Throws if condition not met","`ensureAuthenticated()`"],["`try`","Attempt operation","Returns success/failure, doesn't throw","`tryParse(input)`"],["`initialize/init`","Set up object state","Called once, usually in lifecycle","`initialize(config)`"],["`dispose/close`","Release resources","Called for cleanup, idempotent","`dispose()`, `close()`"]],"caption":"Common Verb Prefixes and Their Semantic Contracts","headers":["Prefix","Semantic Meaning","Expectations","Example"]},"type":"table"},{"data":{"content":"**Semantic Precision Matters**\n\nNotice the subtle but important distinction between `get` and `find`. A `get` method implies the entity is expected to exist; if it doesn't, an exception is thrown. A `find` method implies the entity may or may not exist; null (or Optional/Maybe) is a valid return value.\n\nThis isn't arbitrary—it communicates **intent at the call site**:\n\n```typescript\n// Developer knows this will throw if user doesn't exist\nconst user = userRepository.getUser(id);\n\n// Developer knows they need to handle the null case\nconst user = userRepository.findUserByEmail(email);\nif (user === null) {\n // Handle missing user\n}\n```\n\nWhen these semantic contracts are violated—e.g., a `get` method that returns null—developers write incorrect code based on correct assumptions about API conventions."},"type":"text"},{"data":{"icon":"Info","title":"Language-Specific Conventions","content":"Some languages have established variations. In Python, properties often use `@property` decorators instead of `get_` prefixes. In Ruby, boolean methods end with `?`. In Kotlin, property access syntax is preferred. Always respect language-specific idioms while maintaining semantic clarity.","variant":"note"},"type":"callout"}],"titleType":"number","titleNumber":3},{"id":"method-type-patterns","title":"Naming Patterns for Different Method Types","content":[{"data":{"content":"Different categories of methods have evolved distinct naming patterns. Understanding these patterns helps maintain consistency and set correct expectations."},"type":"text"},{"data":{"tabs":[{"id":"accessor-methods","label":"Accessors & Mutators","content":[{"data":{"content":"$7a"},"type":"text"}]},{"id":"factory-methods","label":"Factory Methods","content":[{"data":{"content":"$7b"},"type":"text"}]},{"id":"command-methods","label":"Command Methods","content":[{"data":{"content":"**Command Method Naming**\n\nCommand methods perform actions, often with side effects. They should use strong, specific verbs that describe the action precisely.\n\n**Prefer Specific Verbs**:\n\n```java\n// Vague — avoid\nvoid handle(Request request)\nvoid process(Order order)\nvoid execute(Task task)\n\n// Specific — prefer\nvoid submitOrder(Order order)\nvoid publishEvent(Event event)\nvoid archiveDocument(Document doc)\nvoid escalateTicket(Ticket ticket)\n```\n\n**Lifecycle Methods**:\n\n```java\n// Initialization\nvoid initialize()\nvoid start()\nvoid open()\nvoid connect()\n\n// Termination\nvoid shutdown()\nvoid stop()\nvoid close()\nvoid disconnect()\nvoid dispose()\n```\n\n**Async/Event Methods**:\n\n```java\n// Prefix with on for event handlers\nvoid onUserCreated(User user)\nvoid onPaymentReceived(Payment payment)\nvoid onConnectionLost()\n\n// Suffix with Async for async operations (language-dependent)\nCompletableFuture submitOrderAsync(Order order)\nPromise fetchDataAsync(Query query)\n```"},"type":"text"}]},{"id":"query-methods","label":"Query Methods","content":[{"data":{"content":"$7c"},"type":"text"}]}]},"type":"tabs"}],"titleType":"number","titleNumber":4},{"id":"naming-anti-patterns","title":"Common Naming Anti-Patterns","content":[{"data":{"content":"Recognizing anti-patterns is as important as knowing best practices. These naming mistakes are pervasive and costly."},"type":"text"},{"data":{"items":["**Generic Verbs** — `handle()`, `process()`, `manage()`, `execute()`, `doStuff()`. These words convey almost no meaning. What does `handleRequest()` do? Validate it? Route it? Transform it? Persist it?","**Misleading Names** — `getUser()` that creates a user if not found violates semantic contracts. `validate()` that modifies data is worse than confusing—it's deceptive.","**Inconsistent Vocabulary** — Using `get`, `fetch`, `retrieve`, and `obtain` interchangeably. Pick one. Consistency enables intuition.","**Technical Jargon** — `marshallData()`, `hydrateEntity()`, `reifyObject()`. Unless your domain inherently uses these terms, prefer `serialize`, `load`, `create`.","**Abbreviations and Acronyms** — `calcMthlyPmt()` is unreadable. `calculateMonthlyPayment()` is clear. Save keystrokes with autocomplete, not cryptic abbreviations.","**Hungarian Notation** — `strName`, `intAge`, `arrItems`. Type information belongs in the type system, not in names. Modern IDEs make this obsolete.","**And/Or in Names** — `validateAndSave()`, `fetchOrCreate()`. This is a code smell indicating the method does too much. Split into separate methods.","**Bool Parameter in Name** — `setEnabled(true)` reads better as `enable()`. `setVisible(false)` reads better as `hide()`. Boolean parameters often indicate a method should be split."],"title":{"icon":"XCircle","text":"Naming Anti-Patterns to Avoid","type":"icon","color":"destructive","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"left":[{"data":{"items":["`processData()`","`handleEvent()`","`doWork()`","`manage()`","`getData()` (returns void)","`fetchOrCreate()`","`getUserIfExistsOr...`","`str_username`"],"title":{"icon":"XCircle","text":"Anti-Pattern Examples","type":"icon","color":"destructive","variant":"outline-circle"},"variant":"accent"},"type":"list"}],"right":[{"data":{"items":["`transformToJson()`","`routeToHandler()`","`executeScheduledTask()`","`startMonitoring()`","`loadData()` (performs action)","`find()` + `create()` separately","`findUser()` (nullable return)","`username`"],"title":{"icon":"CheckCircle","text":"Preferred Alternatives","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"}]},"type":"two-column"},{"data":{"icon":"AlertCircle","title":"The 'And' Smell","content":"When you're tempted to use 'And' or 'Or' in a method name, stop. This almost always indicates a Single Responsibility Principle violation. A method should do one thing. If you need both operations, expose two methods and let the caller compose them—or create a higher-level abstraction that explicitly represents the combined operation.","variant":"error"},"type":"callout"}],"titleType":"number","titleNumber":5},{"id":"consistency-systems","title":"Consistency and Naming Systems","content":[{"data":{"content":"Individual method names matter, but **systematic consistency** matters more. A naming system creates predictability. When developers learn the patterns in one part of your API, they can predict method names across the entire API.\n\n**Establishing a Naming System**\n\nA naming system defines:\n\n1. **Verb vocabulary** — The specific verbs used and their precise meanings\n2. **Grammatical patterns** — How verbs, nouns, and modifiers combine\n3. **Domain terminology** — The nouns and concepts from the problem domain\n4. **Exceptions** — Documented deviations and their rationale"},"type":"text"},{"data":{"code":"$7d","fileName":"naming-system-example.md","languages":[{"label":"Markdown","value":"markdown"}]},"type":"code"},{"data":{"content":"**The Power of Predictability**\n\nWith a documented naming system, developers can predict:\n\n- `getCustomer(id)` exists because `getOrder(id)` exists\n- `findOrdersByCustomer(customerId)` follows the `findXByY` pattern\n- `order.cancel()` exists because `order.submit()` exists\n\nThis predictability dramatically accelerates API adoption and reduces lookup friction."},"type":"text"},{"data":{"icon":"Lightbulb","title":"Document Your Naming Conventions","content":"Create a NAMING_CONVENTIONS.md file in your project. Document the verb vocabulary, grammatical patterns, and any domain-specific rules. Review new method names against this document in code reviews. This investment pays dividends as the team grows and the codebase evolves.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":6},{"id":"context-scope","title":"Context and Naming Scope","content":[{"data":{"content":"Method names don't exist in isolation—they exist within a **context**: the class or module where they're defined. Good naming leverages context to achieve clarity without redundancy.\n\n**Avoid Redundant Context**\n\nWhen a method is called on an object, the object's type is already known. Don't repeat it:"},"type":"text"},{"data":{"left":[{"data":{"code":"// Redundant — class name repeated\nclass Order {\n void cancelOrder() { ... }\n void submitOrder() { ... }\n BigDecimal getOrderTotal() { ... }\n List getOrderLineItems() { ... }\n}\n\n// At call site:\norder.cancelOrder();\norder.getOrderTotal();","fileName":"redundant.java","languages":[{"label":"Java","value":"java"}]},"type":"code"}],"right":[{"data":{"code":"// Clean — context provides clarity\nclass Order {\n void cancel() { ... }\n void submit() { ... }\n BigDecimal getTotal() { ... }\n List getLineItems() { ... }\n}\n\n// At call site:\norder.cancel();\norder.getTotal();","fileName":"clean.java","languages":[{"label":"Java","value":"java"}]},"type":"code"}]},"type":"two-column"},{"data":{"content":"**When Context Is Insufficient**\n\nSometimes, context alone doesn't provide enough clarity. In these cases, additional qualification is appropriate:\n\n```java\nclass User {\n // 'send' alone is ambiguous—send what?\n void sendVerificationEmail() { ... }\n void sendPasswordResetEmail() { ... }\n \n // 'update' alone is ambiguous—update what?\n void updatePassword(String newPassword) { ... }\n void updateProfilePhoto(Image photo) { ... }\n}\n```\n\n**Package/Module Context**\n\nBeyond class context, package or module names also contribute to clarity:\n\n```java\n// In package com.example.payments\nclass PaymentService {\n // 'process' is fine here—the package and class name \n // provide context that makes 'process' unambiguous\n void process(Payment payment) { ... }\n}\n\n// Would be unclear in a more generic package\n// In package com.example.core\nclass Service {\n // process what? This needs qualification\n void process(Object thing) { ... } // BAD\n}\n```"},"type":"text"},{"data":{"icon":"Info","title":"Read Method Calls at Call Sites","content":"Always consider how a method name reads at the call site, not just at the definition site. The call site is where clarity matters most. `paymentService.process(payment)` reads clearly because the variable names provide context. Ensure your naming works well in typical call site scenarios.","variant":"note"},"type":"callout"}],"titleType":"number","titleNumber":7},{"id":"summary","title":"Summary: The Art of Method Naming","content":[{"data":{"content":"Method naming is both an art and a discipline. It requires empathy for API consumers, precision in language, and unwavering consistency. Let's consolidate the key principles:"},"type":"text"},{"data":{"type":"ordered","items":["**Names are the first interface** — Method names are encountered before documentation, before parameters, before everything else. They set expectations.","**Reveal intent, not implementation** — Names should describe *what*, not *how*. Implementation changes; intent should remain stable.","**Use standard verb prefixes** — `get`, `find`, `create`, `delete`, `is`, `has`, `can`, etc. have established meanings. Honor those contracts.","**Be precise, not generic** — Avoid `handle`, `process`, `manage`. Every method should have a name that only it could have.","**Establish naming systems** — Consistency across an API enables predictability. Document your conventions.","**Leverage context** — Don't repeat class names in method names. Context already provides some information.","**Avoid 'And/Or' names** — They signal Single Responsibility violations. Split methods instead.","**Optimize for the call site** — Methods are read at call sites far more often than defined. Prioritize readability there."],"title":{"icon":"CheckCircle","text":"Key Takeaways","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"content":"**What's Next**\n\nMethod names are only one component of method signatures. The next page examines **parameter design**—how to choose parameter types, orderings, and counts that make methods intuitive and hard to misuse."},"type":"text"},{"data":{"icon":"CheckCircle","title":"Page Complete","content":"You now understand the principles, patterns, and anti-patterns of method naming. These skills will serve you in every API you design and every code review you conduct. Next, we'll explore how to design parameters that make your methods even more intuitive and robust.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":8}],"isLocked":false},{"id":"seed_8744b3ce268d5959ab56cd8ca8b54e24","title":"Parameter Design","order":1,"content":null,"isLocked":true},{"id":"seed_fccf7ea9d8a2daa608b96b064f18a1cb","title":"Return Type Design","order":2,"content":null,"isLocked":true},{"id":"seed_ab334f13567bd62a943e5ce5bac9b8f2","title":"Overloading Guidelines","order":3,"content":null,"isLocked":true}]}}