Terminology & Style

Kosmos DSL 전반에서 사용하는 용어/네이밍 규칙과 코딩 스타일을 정의합니다. 팀 전체가 같은 단어와 규칙으로 말하면 유지보수가 쉬워집니다.

주요 용어

외부 DSL (사용자 API)

  • css(...): 클래스 추가 (여러 개 공백 구분)
  • attr(name, value): 속성 추가
  • text(...): 텍스트 노드 설정
  • child(...), children(...): 자식(들) 추가
  • El.*: 요소 팩토리(div/a/img/table...)

내부 DSL (엔진 내부)

  • addClass / addAttribute / addChild(s)
  • HtmlComponent: render(ctx)를 구현하는 타입
  • HtmlTag / VoidTag: 자식 유무로 구분
  • RenderContext: 요청/세션/권한/언어 등 컨텍스트

네이밍 규칙

범주 권장 지양
Template *PageTemplate (페이지 레이아웃/슬롯 제공) 복잡한 화면 로직 혼재
Fragment Frag* (Organism; 페이지 조각의 조합) Controller 로직 포함
Component Comp* (Molecule/Atom; 재사용 단위) 페이지 전역 상태 의존
변수/함수 lowerCamelCase, 동사+명사 (예: buildTable()) 약어 남용, 의미 없는 축약
패키지 단일 책임 (예: dsl.component) 역할 혼합(유틸·컴포넌트·서비스 뒤섞임)

코드 심화: 버튼 컴포넌트 표준화

버튼 스타일과 접근성 속성을 통일하면, 화면 간 일관성이 좋아집니다.

public class CompPrimaryButton implements HtmlComponent {
  private final String label;
  private final String href;
  public CompPrimaryButton(String label, String href) {
    this.label = label; this.href = href;
  }
  @Override public String render(RenderContext ctx) {
    return El.a().css("btn btn-primary")
        .attr("href", href)
        .attr("role", "button")
        .attr("aria-label", label)
        .text(label)
        .render(ctx);
  }
}

스타일 가이드: 예 / 아님

예 (Good) 아님 (Bad) 
El.a().css("btn btn-outline-secondary")
  .attr("href","/docs")
  .text("문서");
 
El.a().css("button-gray")
  .attr("href","/docs")
  .text("문서"); // 팀 표준과 불일치
 
// 텍스트는 메시지 키 사용
text(i18n("docs.link"));
 
// 하드코딩
text("문서 보기");

접근성 & 국제화 체크리스트

  • 의미 있는 HTML 태그 선택 (제목은 h1~h6, 목록은 ul/ol)
  • 버튼/링크에 role, aria-label 등 보조 속성 적용
  • 문자열은 메시지 번들 키로 관리하여 다국어 확장
  • 색만으로 의미를 전달하지 말기(아이콘/텍스트 병행)

주의사항

혼용 금지: 외부 DSL(사용자 API)와 내부 엔진 API 네이밍을 섞어 쓰지 마세요.
안티 패턴: 인라인 스타일/임의 클래스명 남용 → 재사용성과 유지보수 저하.
리뷰 규칙: PR 템플릿에 네이밍/접근성 체크 항목을 포함하세요.